Bento, the office suite that fits in a file
TypeScript mit-licenseofficeoffice-365office-suiteoffice-toolsoffice365open-sourcepowerpointself-hostedsingle-page-appslidesslideshareslideshowslideshow-galleryslideshow-makerslideshows
// SPDX-License-Identifier: MIT
// Copyright (c) 2026 The Bento authors
//
// bento/id — the recovery code and the key blobs (identity-design §2f, signed by
// security §28). The reference for every host that wraps or unwraps an account
// key, with conformance vectors in kernel/fixtures/identity-v1.json.
//
// Two ways back into an account on a new device, neither held by Bento:
// - a PASSKEY with the PRF extension: its 32-byte PRF output derives a key that
// unwraps the account key from a blob the directory keeps per passkey;
// - a RECOVERY CODE printed once at setup: Argon2id stretches it into the key
// for a second blob, which the directory releases only at the end of the
// tightened recovery (72 h wait, every device notified).
//
// Argon2id is not in WebCrypto, and documents never derive these keys (only an
// agent does), so this module takes the Argon2id function as a parameter: the
// extension passes its vendored WASM, the rigs pass Node's native one, and the
// kernel ships no WASM. Everything else here is WebCrypto (HKDF, AES-GCM, HMAC).
import { b64uEnc, b64uDec, sha256b64u, type Verdict, type KxMode, KX_MODE } from './statements.ts'
// --- parameters (security §28) -------------------------------------------------
/** Argon2id, version 0x13. p = 1 is safest for WASM and phones. */
export const ARGON2 = Object.freeze({ version: 0x13, parallelism: 1, memoryKiB: 65536, passes: 3, tagLength: 32 })
/** Salt lengths. The wrap salt and the verifier salt are separate and independent. */
export const SALT_LEN = 16
/** Argon2id with ARGON2's parameters, supplied by the host. */
export type Argon2id = (password: Uint8Array, salt: Uint8Array) => Promise<Uint8Array>
const no = (reason: string): { ok: false; reason: string } => ({ ok: false, reason })
const te = new TextEncoder()
// --- the recovery code: 80 bits, Crockford base32, with a check symbol ----------
/** Crockford base32: digits and letters without I, L, O, U. */
const ALPHABET = '0123456789ABCDEFGHJKMNPQRSTVWXYZ'
/** Check symbols: the 32 above plus * ~ $ = U for values 32–36 (mod 37). */
const CHECK_ALPHABET = ALPHABET + '*~$=U'
export const CODE_BYTES = 10 // 80 bits = 16 symbols
const toBig = (b: Uint8Array) => b.reduce((x, v) => (x << 8n) | BigInt(v), 0n)
/** The 80-bit value mod 37, in a fixed 10-step loop (no BigInt on the code). */
const check37 = (code: Uint8Array) => code.reduce((r, b) => (r * 256 + b) % 37, 0)
/** The printed form: XXXX-XXXX-XXXX-XXXX-C. */
export function formatRecoveryCode(code: Uint8Array): string {
if (code.length !== CODE_BYTES) throw new Error('a recovery code is 10 bytes')
let s = ''
for (let i = 0; i < 16; i++) { // symbol i is bits 5i..5i+4 from the top
const bit = i * 5, byte = bit >> 3, sh = bit & 7
const two = (code[byte] << 8) | (code[byte + 1] ?? 0)
s += ALPHABET[(two >> (11 - sh)) & 31]
}
return `${s.slice(0, 4)}-${s.slice(4, 8)}-${s.slice(8, 12)}-${s.slice(12, 16)}-${CHECK_ALPHABET[check37(code)]}`
}
export type CodeRefusal = 'length' | 'character' | 'check'
/**
* Read what a person typed. Forgiving where Crockford is: case, spaces and
* hyphens don't matter, and O reads as 0, I and L as 1. The check symbol must
* match, so a typo is caught HERE, before it costs one of the directory's five
* daily attempts. Returns the 10 bytes Argon2id takes — never the string, so no
* two hosts can disagree about case or separators.
*/
export function parseRecoveryCode(input: string): { ok: true; code: Uint8Array } | { ok: false; reason: CodeRefusal } {
const s = input.toUpperCase().replace(/[\s-]/g, '').replace(/O/g, '0').replace(/[IL]/g, '1')
if (s.length !== 17) return { ok: false, reason: 'length' }
const code = new Uint8Array(CODE_BYTES)
for (let i = 0; i < 16; i++) {
const v = ALPHABET.indexOf(s[i])
if (v < 0) return { ok: false, reason: 'character' } // includes U: valid only as the check
const bit = i * 5, byte = bit >> 3, sh = bit & 7
const two = v << (11 - sh) // the symbol placed in a 16-bit window over bytes byte, byte+1
code[byte] |= two >> 8
if (byte + 1 < CODE_BYTES) code[byte + 1] |= two & 0xff
}
const check = CHECK_ALPHABET.indexOf(s[16])
if (check < 0) return { ok: false, reason: 'character' }
if (check !== check37(code)) return { ok: false, reason: 'check' }
return { ok: true, code }
}
// --- derivations ------------------------------------------------------------------
async function hkdf(ikm: Uint8Array, salt: Uint8Array, info: string): Promise<Uint8Array> {
const k = await crypto.subtle.importKey('raw', ikm as BufferSource, 'HKDF', false, ['deriveBits'])
return new Uint8Array(await crypto.subtle.deriveBits(
{ name: 'HKDF', hash: 'SHA-256', salt: salt as BufferSource, info: te.encode(info) as BufferSource }, k, 256))
}
/** HKDF's salt is EMPTY where a step needs none (equivalent to 32 zero bytes). */
const EMPTY = new Uint8Array(0)
/** The recovery blob's wrap key: HKDF-SHA-256(Argon2id(code, salt), empty, "bento/id/rc-wrap/v1"). */
export async function recoveryWrapKey(code: Uint8Array, salt: Uint8Array, argon2: Argon2id): Promise<Uint8Array> {
checkLen(code, CODE_BYTES, 'code'); checkLen(salt, SALT_LEN, 'salt')
return hkdf(await argon2(code, salt), EMPTY, 'bento/id/rc-wrap/v1')
}
/** What the client sends the directory to prove it knows the code: Argon2id(code, salt_v). */
export async function recoveryVerifier(code: Uint8Array, saltV: Uint8Array, argon2: Argon2id): Promise<Uint8Array> {
checkLen(code, CODE_BYTES, 'code'); checkLen(saltV, SALT_LEN, 'salt_v')
return argon2(code, saltV)
}
/**
* The PRF extension's FIXED input (identity-design §2f), as UTF-8 bytes: every
* ceremony evaluates exactly this, so one passkey always yields one PRF output.
*/
export const PRF_INPUT = 'bento/id/prf/v1'
/**
* What a host that speaks CTAP directly (libfido2 hmac-secret, no WebAuthn PRF
* API) must send as the hmac-secret salt so the authenticator returns the SAME
* 32 bytes a browser's PRF extension would. WebAuthn Level 3 §10.1.4:
* salt = SHA-256(UTF-8("WebAuthn PRF") ‖ 0x00 ‖ input). Forget the 0x00, or
* send the raw input, and the blob you seal can never be opened by a browser
* (and vice versa). Browsers do this themselves; never apply it twice.
*/
export async function prfHmacSecretSalt(input: Uint8Array = te.encode(PRF_INPUT)): Promise<Uint8Array> {
const label = te.encode('WebAuthn PRF')
const msg = new Uint8Array(label.length + 1 + input.length)
msg.set(label); msg[label.length] = 0; msg.set(input, label.length + 1)
return new Uint8Array(await crypto.subtle.digest('SHA-256', msg as BufferSource))
}
/** The PRF blob's key: HKDF-SHA-256(PRF output, 32-byte salt, "bento/id/acct-wrap/v1"). */
export async function prfKek(prfOutput: Uint8Array, salt: Uint8Array): Promise<Uint8Array> {
checkLen(prfOutput, 32, 'PRF output'); checkLen(salt, 32, 'salt')
return hkdf(prfOutput, salt, 'bento/id/acct-wrap/v1')
}
function checkLen(b: Uint8Array, n: number, what: string) {
if (!(b instanceof Uint8Array) || b.length !== n) throw new Error(`${what} must be ${n} bytes`)
}
// --- the blob plaintext: raw private scalars, checked on import ------------------
/** P-256 */
const P = 0xffffffff00000001000000000000000000000000ffffffffffffffffffffffffn
const N = 0xffffffff00000000ffffffffffffffffbce6faada7179e84f3b9cac2fc632551n
const GX = 0x6b17d1f2e12c4247f8bce6e563a440f277037d812deb33a0f4a13945d898c296n
const GY = 0x4fe342e2fe1a7f9b8ee7eb4a7c0f9e162bce33576b315ececbb6406837bf51f5n
const mod = (a: bigint) => ((a % P) + P) % P
function inv(a: bigint): bigint { // Fermat: a^(p-2)
let r = 1n, b = mod(a), e = P - 2n
while (e > 0n) { if (e & 1n) r = (r * b) % P; b = (b * b) % P; e >>= 1n }
return r
}
type J = [bigint, bigint, bigint] // Jacobian; Z = 0 is the point at infinity
function dbl([x, y, z]: J): J {
if (y === 0n || z === 0n) return [0n, 1n, 0n]
const z2 = mod(z * z), m = mod(3n * (x - z2) * (x + z2)) // a = -3
const y2 = mod(y * y), s = mod(4n * x * y2)
const x3 = mod(m * m - 2n * s), y3 = mod(m * (s - x3) - 8n * y2 * y2), z3 = mod(2n * y * z)
return [x3, y3, z3]
}
function add(p: J, q: J): J {
if (p[2] === 0n) return q
if (q[2] === 0n) return p
const z1z1 = mod(p[2] * p[2]), z2z2 = mod(q[2] * q[2])
const u1 = mod(p[0] * z2z2), u2 = mod(q[0] * z1z1)
const s1 = mod(p[1] * q[2] * z2z2), s2 = mod(q[1] * p[2] * z1z1)
if (u1 === u2) return s1 === s2 ? dbl(p) : [0n, 1n, 0n]
const h = mod(u2 - u1), r = mod(s2 - s1), h2 = mod(h * h), h3 = mod(h * h2)
const x3 = mod(r * r - h3 - 2n * u1 * h2)
return [x3, mod(r * (u1 * h2 - x3) - s1 * h3), mod(h * p[2] * q[2])]
}
/** The public key (raw uncompressed point, base64url) of a 32-byte private
* scalar in 1..n−1. Plain P-256 arithmetic, so it is identical on every host;
* null for a scalar out of range. */
export function publicKeyOf(scalar: Uint8Array): string | null {
if (!(scalar instanceof Uint8Array) || scalar.length !== 32) return null
const d = toBig(scalar)
return d >= 1n && d < N ? publicOf(d) : null
}
/** d·G as a raw uncompressed point (65 bytes), base64url. */
function publicOf(d: bigint): string {
let acc: J = [0n, 1n, 0n], base: J = [GX, GY, 1n]
for (let k = d; k > 0n; k >>= 1n) { if (k & 1n) acc = add(acc, base); base = dbl(base) }
const zi = inv(acc[2]), zi2 = mod(zi * zi)
const x = mod(acc[0] * zi2), y = mod(acc[1] * zi2 * zi)
const out = new Uint8Array(65); out[0] = 4
for (let i = 0, v = x; i < 32; i++) { out[32 - i] = Number(v & 0xffn); v >>= 8n }
for (let i = 0, v = y; i < 32; i++) { out[64 - i] = Number(v & 0xffn); v >>= 8n }
return b64uEnc(out)
}
/** Which scalars a blob carries, by the kx placement (identity-design §6b). */
const BLOB_KX: Record<KxMode, boolean> = { unruled: false, A: true, B: false, C: true }
export interface BlobKeys {
/** the account signing key's private scalar, 32 bytes big-endian */
account: Uint8Array
/** the kx private scalar — the shared kx (A) or the recovery kx (C); absent otherwise */
kx?: Uint8Array
}
/** account d ‖ kx d (when the mode carries one), each 32 bytes big-endian. */
export function packScalars(keys: BlobKeys, mode: KxMode = KX_MODE): Uint8Array {
checkLen(keys.account, 32, 'account scalar')
if (!BLOB_KX[mode]) {
if (keys.kx) throw new Error(`kx mode ${mode} carries no kx in the blob`)
return keys.account.slice()
}
if (!keys.kx) throw new Error(`kx mode ${mode} needs a kx in the blob`)
checkLen(keys.kx, 32, 'kx scalar')
const out = new Uint8Array(64); out.set(keys.account); out.set(keys.kx, 32)
return out
}
/**
* Read a blob's plaintext and CHECK it before anything uses it: the right length
* for the mode, every scalar in 1..n−1 (security §28), and each one's public
* half equal to the public key in the directory-signed binding. A blob swapped by
* a malicious directory fails closed here.
*
* These are RECOVERED PRIVATE SCALARS, so nothing here branches on their bits.
* The range check is a branch-free byte compare, and the match goes through the
* platform's crypto, never publicOf (variable-time double-and-add on BigInt,
* kept for the generator and the rig only). The scalar is imported as a JWK
* {d, x, y} with x, y from the stated public half (Chrome and Node refuse a
* mismatched pair), then signs a probe that must verify under that public key,
* so a platform that skips the pair check on import is caught too (security, #770).
*/
export async function unpackScalars(pt: Uint8Array, expected: { accountPub: string; kxPub?: string }, mode: KxMode = KX_MODE,
subtle: SubtleCrypto = crypto.subtle): Promise<Verdict<BlobKeys>> {
const withKx = BLOB_KX[mode]
if (pt.length !== (withKx ? 64 : 32)) return no('length')
const scalars = withKx ? [pt.slice(0, 32), pt.slice(32)] : [pt.slice(0, 32)]
const pubs = withKx ? [expected.accountPub, expected.kxPub] : [expected.accountPub]
for (let i = 0; i < scalars.length; i++) {
if (!scalarInRange(scalars[i])) return no('scalar-range')
if (pubs[i] === undefined || !(await scalarMatches(scalars[i], pubs[i]!, subtle))) return no('key-mismatch')
}
return { ok: true, value: withKx ? { account: scalars[0], kx: scalars[1] } : { account: scalars[0] } }
}
const N_BYTES = Uint8Array.from({ length: 32 }, (_, i) => Number((N >> BigInt(8 * (31 - i))) & 0xffn))
/** 1 ≤ d < n for a 32-byte big-endian scalar, without branching on its bytes. */
function scalarInRange(d: Uint8Array): boolean {
let nonzero = 0, lt = 0, gt = 0
for (let i = 0; i < 32; i++) {
const a = d[i], b = N_BYTES[i], open = 1 ^ (lt | gt)
lt |= open & (((a - b) >>> 31) & 1)
gt |= open & (((b - a) >>> 31) & 1)
nonzero |= a
}
return (lt & ((nonzero | -nonzero) >>> 31)) === 1
}
const PROBE = te.encode('bento/id/scalar-probe/v1')
const ECDSA_P256 = { name: 'ECDSA', namedCurve: 'P-256' }
/** Does the private scalar d belong to the raw public key pub? Platform crypto only.
* `subtle` is injectable so a rig can stand in a platform that skips the pair check on import. */
async function scalarMatches(d: Uint8Array, pub: string, subtle: SubtleCrypto): Promise<boolean> {
const raw = b64uDec(pub)
if (!raw || raw.length !== 65 || raw[0] !== 4) return false
try {
const priv = await subtle.importKey('jwk', {
kty: 'EC', crv: 'P-256', d: b64uEnc(d), x: b64uEnc(raw.slice(1, 33)), y: b64uEnc(raw.slice(33)), ext: false,
}, ECDSA_P256, false, ['sign'])
const pubKey = await subtle.importKey('raw', raw as BufferSource, ECDSA_P256, false, ['verify'])
const sig = await subtle.sign({ name: 'ECDSA', hash: 'SHA-256' }, priv, PROBE as BufferSource)
return await subtle.verify({ name: 'ECDSA', hash: 'SHA-256' }, pubKey, sig, PROBE as BufferSource)
} catch { return false }
}
// --- AES-256-GCM ---------------------------------------------------------------------
async function gcm(op: 'encrypt' | 'decrypt', key: Uint8Array, iv: Uint8Array, aad: string, data: Uint8Array) {
checkLen(key, 32, 'key'); checkLen(iv, 12, 'iv')
const k = await crypto.subtle.importKey('raw', key as BufferSource, 'AES-GCM', false, [op])
const params = { name: 'AES-GCM', iv: iv as BufferSource, additionalData: te.encode(aad) as BufferSource, tagLength: 128 }
return new Uint8Array(op === 'encrypt'
? await crypto.subtle.encrypt(params, k, data as BufferSource)
: await crypto.subtle.decrypt(params, k, data as BufferSource))
}
const accountTag = async (accountPub: string) => sha256b64u(accountPub)
// --- the PRF blob (one per passkey) -----------------------------------------------
export interface PrfBlob { v: 1; cred: string; salt: string; iv: string; ct: string }
/** cred = b64u(sha256(credentialId)); aad = "bento/id/acct-wrap/v1." ‖ cred; ct = ciphertext ‖ tag. */
export async function sealPrfBlob(a: {
prfOutput: Uint8Array; credentialId: Uint8Array; salt: Uint8Array; iv: Uint8Array; keys: BlobKeys; mode?: KxMode
}): Promise<PrfBlob> {
const cred = b64uEnc(new Uint8Array(await crypto.subtle.digest('SHA-256', a.credentialId as BufferSource)))
const kek = await prfKek(a.prfOutput, a.salt)
const ct = await gcm('encrypt', kek, a.iv, `bento/id/acct-wrap/v1.${cred}`, packScalars(a.keys, a.mode))
return { v: 1, cred, salt: b64uEnc(a.salt), iv: b64uEnc(a.iv), ct: b64uEnc(ct) }
}
export async function openPrfBlob(blob: PrfBlob, a: {
prfOutput: Uint8Array; credentialId: Uint8Array; expected: { accountPub: string; kxPub?: string }; mode?: KxMode
}): Promise<Verdict<BlobKeys>> {
if (blob?.v !== 1) return no('version')
const cred = b64uEnc(new Uint8Array(await crypto.subtle.digest('SHA-256', a.credentialId as BufferSource)))
if (blob.cred !== cred) return no('credential')
const salt = b64uDec(blob.salt), iv = b64uDec(blob.iv), ct = b64uDec(blob.ct)
if (!salt || salt.length !== 32 || !iv || iv.length !== 12 || !ct) return no('grammar')
let pt: Uint8Array
try { pt = await gcm('decrypt', await prfKek(a.prfOutput, salt), iv, `bento/id/acct-wrap/v1.${cred}`, ct) } catch { return no('decrypt') }
return unpackScalars(pt, a.expected, a.mode)
}
// --- the recovery-code blob, and the directory's pepper layer ---------------------
/** Inner layer: AES-GCM(rc wrap key, scalars), aad = "bento/id/rc-wrap/v1." ‖ b64u(sha256(accountPub)). */
export async function sealRecoveryInner(a: { wrapKey: Uint8Array; iv: Uint8Array; accountPub: string; keys: BlobKeys; mode?: KxMode }):
Promise<Uint8Array> {
return gcm('encrypt', a.wrapKey, a.iv, `bento/id/rc-wrap/v1.${await accountTag(a.accountPub)}`, packScalars(a.keys, a.mode))
}
export async function openRecoveryInner(ct: Uint8Array, a: {
wrapKey: Uint8Array; iv: Uint8Array; expected: { accountPub: string; kxPub?: string }; mode?: KxMode
}): Promise<Verdict<BlobKeys>> {
let pt: Uint8Array
try { pt = await gcm('decrypt', a.wrapKey, a.iv, `bento/id/rc-wrap/v1.${await accountTag(a.expected.accountPub)}`, ct) } catch { return no('decrypt') }
return unpackScalars(pt, a.expected, a.mode)
}
/**
* The directory's per-account pepper (server side; share implements it, this is
* the reference for its vectors). From one versioned Worker secret PEPPER_vN:
* P = HKDF(PEPPER_vN, empty, "bento/id/pepper/v1." ‖ b64u(sha256(accountPub)))
* verifyKey = HKDF(P, empty, "bento/id/pepper/v1/verify")
* — the stored verifier is HMAC-SHA-256(verifyKey, verifier)
* wrapKey = HKDF(P, empty, "bento/id/pepper/v1/wrap")
* — the outer AES-GCM layer over the inner ciphertext,
* aad = "bento/id/rc-pepper/v1." ‖ b64u(sha256(accountPub))
* The subkey labels are fully domain-separated (security §28a).
*/
export async function pepperKeys(pepper: Uint8Array, accountPub: string): Promise<{ verifyKey: Uint8Array; wrapKey: Uint8Array }> {
const p = await hkdf(pepper, EMPTY, `bento/id/pepper/v1.${await accountTag(accountPub)}`)
return { verifyKey: await hkdf(p, EMPTY, 'bento/id/pepper/v1/verify'), wrapKey: await hkdf(p, EMPTY, 'bento/id/pepper/v1/wrap') }
}
export async function pepperVerifierTag(verifyKey: Uint8Array, verifier: Uint8Array): Promise<Uint8Array> {
const k = await crypto.subtle.importKey('raw', verifyKey as BufferSource, { name: 'HMAC', hash: 'SHA-256' }, false, ['sign'])
return new Uint8Array(await crypto.subtle.sign('HMAC', k, verifier as BufferSource))
}
export async function pepperSeal(wrapKey: Uint8Array, iv: Uint8Array, inner: Uint8Array, accountPub: string): Promise<Uint8Array> {
return gcm('encrypt', wrapKey, iv, `bento/id/rc-pepper/v1.${await accountTag(accountPub)}`, inner)
}
export async function pepperOpen(wrapKey: Uint8Array, iv: Uint8Array, outer: Uint8Array, accountPub: string): Promise<Uint8Array | null> {
try { return await gcm('decrypt', wrapKey, iv, `bento/id/rc-pepper/v1.${await accountTag(accountPub)}`, outer) } catch { return null }
}