Previewkernable is not released yet: these docs describe work in progress, and things may change before 1.0.Not released yet.Request early access →
Skip to content

7. Personal data ​

Events are kept forever and form a signed hash chain: you cannot change or delete one. But customers have a right to have their personal data erased, and passwords should not be stored at all. kernable keeps such values in a vault next to the log:

  • The log stores a reference instead of the value: {"$vault": "3fa9…"}. The reference is salted, so it reveals nothing about the value, also once the value is gone.
  • The vault keeps the values encrypted, and deletes them for real.
  • Personal values belong to a person (a subject) and are deleted when an event erases that person.
  • Secret values, like passwords, are deleted as soon as their command completed.

The kernel you started in part 1 already has a vault: --dev turned it on with vault.key, and it keeps the values in vault.db.

Declare what is personal ​

In domain.ts, declare per command and event which fields go to the vault, and for whom; add passwords and erasure to the customer:

ts
// Personal data goes to the kernel's vault; the signed log keeps references only.
shopDomain.command("Register").personal(["email", "name"], (_d, id) => id);
shopDomain.event("CustomerRegistered", 1).personal(["email", "name"], (_d, id) => id);
shopDomain.command("Confirm").personal(["email"], (d: { customerId: string }) => d.customerId);
shopDomain.event("OrderConfirmed", 1).personal(["email"], (d: { customerId: string }) => d.customerId);
// Passwords are secrets: the handler sees them once; the vault deletes them when it is done.
shopDomain.command("SetPassword").secret(["password"]);
shopDomain.command("SignIn").secret(["password"]);
shopDomain.event("PasswordSet", 1).personal(["hash", "salt"], (_d, id) => id);
// Erasing a customer deletes their personal data everywhere, in every stream.
shopDomain.event("CustomerErased", 1).erases((_d, id) => id);

const hash = (password: string, salt: string) => scryptSync(password, salt, 32).toString("hex");

customerAggregate
  .apply("PasswordSet", (s, data: { hash: string; salt: string }) => { s.passwordHash = data.hash; s.salt = data.salt; })
  .apply("CustomerErased", (s) => { delete s.passwordHash; delete s.salt; s.registered = false; })
  .command("SetPassword", (s, data: { password: string }, _cmd, ctx) => {
    if (!s.registered) throw new Rejected("No such customer", "not_found");
    if ((data.password ?? "").length < 8) throw new Rejected("At least 8 characters", "invalid");
    const salt = ctx.id(); // deterministic: the command may run again
    return [{ type: "PasswordSet", data: { hash: hash(data.password, salt), salt } }];
  })
  .command("SignIn", (s, data: { password: string }) => {
    if (!s.passwordHash || hash(data.password ?? "", s.salt!) !== s.passwordHash) throw new Rejected("Wrong customer or password", "denied");
    return [{ type: "SignedIn" }];
  })
  .command("Erase", (s) => {
    if (!s.registered) throw new Rejected("No such customer", "not_found");
    return [{ type: "CustomerErased" }];
  });
py
# Personal data goes to the kernel's vault; the signed log keeps references only.
shop_domain.command("Register").personal(["email", "name"], lambda d, customer_id: customer_id)
shop_domain.event("CustomerRegistered", 1).personal(["email", "name"], lambda d, customer_id: customer_id)
shop_domain.command("Confirm").personal(["email"], lambda d: d["customerId"])
shop_domain.event("OrderConfirmed", 1).personal(["email"], lambda d: d["customerId"])
# Passwords are secrets: the handler sees them once; the vault deletes them when it is done.
shop_domain.command("SetPassword").secret(["password"])
shop_domain.command("SignIn").secret(["password"])
shop_domain.event("PasswordSet", 1).personal(["hash", "salt"], lambda d, customer_id: customer_id)
# Erasing a customer deletes their personal data everywhere, in every stream.
shop_domain.event("CustomerErased", 1).erases(lambda d, customer_id: customer_id)


def password_hash(password: str, salt: str) -> str:
    return hashlib.scrypt(password.encode(), salt=salt.encode(), n=2**14, r=8, p=1, dklen=32).hex()


@customer_aggregate.apply("PasswordSet")
def _(state, data):
    state["password_hash"] = data["hash"]
    state["salt"] = data["salt"]


@customer_aggregate.apply("CustomerErased")
def _(state, data):
    state.pop("password_hash", None)
    state.pop("salt", None)
    state["registered"] = False


@customer_aggregate.command("SetPassword")
def _(state, data, cmd, ctx):
    if not state["registered"]:
        raise Rejected("No such customer", "not_found")
    if len(data.get("password") or "") < 8:
        raise Rejected("At least 8 characters", "invalid")
    salt = ctx.id()  # deterministic: the command may run again
    return [{"type": "PasswordSet", "data": {"hash": password_hash(data["password"], salt), "salt": salt}}]


@customer_aggregate.command("SignIn")
def _(state, data):
    if "password_hash" not in state or password_hash(data.get("password") or "", state["salt"]) != state["password_hash"]:
        raise Rejected("Wrong customer or password", "denied")
    return [{"type": "SignedIn"}]


@customer_aggregate.command("Erase")
def _(state, data):
    if not state["registered"]:
        raise Rejected("No such customer", "not_found")
    return [{"type": "CustomerErased"}]
rs
#[derive(Deserialize)]
struct Password {
    password: Option<String>,
}

#[derive(Serialize, Deserialize)]
struct PasswordSet {
    hash: String,
    salt: String,
}

fn vault(shop_domain: &Domain, customer_aggregate: &Aggregate<Customer>) {
    let aggregate = |_: &Value, id: &str| id.to_owned();
    let customer_id = |d: &Value, _: &str| d["customerId"].as_str().unwrap_or_default().to_owned();
    // Personal data goes to the kernel's vault; the signed log keeps references only.
    shop_domain
        .command("Register")
        .personal(&["email", "name"], aggregate);
    shop_domain
        .event("CustomerRegistered", 1)
        .personal(&["email", "name"], aggregate);
    shop_domain
        .command("Confirm")
        .personal(&["email"], customer_id);
    shop_domain
        .event("OrderConfirmed", 1)
        .personal(&["email"], customer_id);
    // Passwords are secrets: the handler sees them once; the vault deletes them when it is done.
    shop_domain.command("SetPassword").secret(&["password"]);
    shop_domain.command("SignIn").secret(&["password"]);
    shop_domain
        .event("PasswordSet", 1)
        .personal(&["hash", "salt"], aggregate);
    // Erasing a customer deletes their personal data everywhere, in every stream.
    shop_domain.event("CustomerErased", 1).erases(aggregate);

    customer_aggregate.apply("PasswordSet", |s, data: PasswordSet, _evt, _ctx| {
        s.password_hash = Some(data.hash);
        s.salt = Some(data.salt);
    });
    customer_aggregate.apply("CustomerErased", |s, _: Value, _evt, _ctx| {
        *s = Customer::default()
    });
    customer_aggregate.command("SetPassword", |s, data: Password, _cmd, ctx| {
        if !s.registered {
            return Err(Rejected::new("No such customer").code("not_found"));
        }
        let password = data.password.unwrap_or_default();
        if password.chars().count() < 8 {
            return Err(Rejected::new("At least 8 characters").code("invalid"));
        }
        let salt = ctx.id(); // deterministic: the command may run again
        Ok(vec![NewEvent::new(
            "PasswordSet",
            PasswordSet {
                hash: hash(&password, &salt),
                salt,
            },
        )])
    });
    customer_aggregate.command("SignIn", |s, data: Password, _cmd, _ctx| {
        let password = data.password.unwrap_or_default();
        match (&s.password_hash, &s.salt) {
            (Some(stored), Some(salt)) if hash(&password, salt) == *stored => {
                Ok(vec![NewEvent::new("SignedIn", ())])
            }
            _ => Err(Rejected::new("Wrong customer or password").code("denied")),
        }
    });
    customer_aggregate.command("Erase", |s, _: Value, _cmd, _ctx| {
        if !s.registered {
            return Err(Rejected::new("No such customer").code("not_found"));
        }
        Ok(vec![NewEvent::new("CustomerErased", ())])
    });
}

/// scrypt with the parameters of the TypeScript and Python shops, so their hashes match.
fn hash(password: &str, salt: &str) -> String {
    let params = scrypt::Params::new(14, 8, 1, 32).expect("valid scrypt parameters");
    let mut out = [0u8; 32];
    scrypt::scrypt(password.as_bytes(), salt.as_bytes(), &params, &mut out).expect("32 bytes fit");
    out.iter().map(|b| format!("{b:02x}")).collect()
}

The handlers do not change: they still see email and password in clear. The SDK moves the fields to the vault before a command or event is signed, and puts them back for the processes allowed to read them.

Two actions of a grant decide who that is:

  • vault_read lists the events and commands whose vault values a listener or middleware gets in clear. A read model that shows email addresses needs it; a guard that only compares IDs does not, and sees the references.
  • vault_erase lists the erasing events a worker may write. Erasing is final, so grant it only for the events meant for it: vault_erase=shop.CustomerErased.

app, which --dev lets do everything, has both. Part 8 grants them per service.

Read models hold values too, so they must forget an erased customer. In read-models.ts:

ts
// An erased customer's personal data must not outlive the erasure in a read model either.
customersReadmodel.on("CustomerErased", (_data, evt) => void customers.delete(evt.aggregateId));
ordersReadmodel.on("CustomerErased", (_data, evt) => {
  for (const row of orders.values()) if (row.customerId === evt.aggregateId && row.confirmedTo) row.confirmedTo = null;
});
py
# An erased customer's personal data must not outlive the erasure in a read model either.
@customers_readmodel.on("CustomerErased")
def _(data, evt):
    customers.pop(evt.aggregate_id, None)


@orders_readmodel.on("CustomerErased")
def _(data, evt):
    for row in orders.values():
        if row["customerId"] == evt.aggregate_id and row.get("confirmedTo"):
            row["confirmedTo"] = None
rs
// An erased customer's personal data must not outlive the erasure in a read model either.
let rows = Arc::clone(&customers);
customers_readmodel.on("CustomerErased", move |_: Value, evt, _ctx| {
    rows.lock().unwrap().remove(&evt.aggregate_id);
    async { Ok(()) }
});
let rows = Arc::clone(&orders);
orders_readmodel.on("CustomerErased", move |_: Value, evt, _ctx| {
    for row in rows.lock().unwrap().values_mut() {
        if row.customer_id == evt.aggregate_id && row.confirmed_to.is_some() {
            row.confirmed_to = Some(None);
        }
    }
    async { Ok(()) }
});

Clients that send commands with personal or secret fields need the declarations: create them with .use(shopDomain), as the reactor in part 4 already does.

Try it ​

Restart every process, then:

ts
// use(shopDomain): the client moves the fields the domain declares personal or secret to the vault.
const kernable = new Kernable({ context: { senderIdentity: "c1" } }).use(shopDomain);
const customer = (type: string, data?: object) => kernable.submit({ domain: "shop", aggregateType: "customer", aggregateId: "c1", type, data });

show("register", await customer("Register", { email: "ann@example.com", name: "Ann" }));
show("set password", await customer("SetPassword", { password: "correct horse" }));
show("sign in, wrong password", await customer("SignIn", { password: "wrong horse" }));
show("sign in", await customer("SignIn", { password: "correct horse" }));
console.log(await kernable.query({ domain: "shop", type: "GetCustomer", data: { id: "c1" } }));
show("erase", await customer("Erase"));
// Erased: the customer's data is gone, and with it the right to act.
await kernable.query({ domain: "shop", type: "GetCustomer", data: { id: "c1" } }).catch((err) => console.log(`read: ${err.code}`));
py
# use(shop_domain): the client moves the fields the domain declares personal or secret to the vault.
k = Kernable(context=RequestContext(sender_identity="c1")).use(shop_domain)


def customer(type, data=None):
    return k.submit("shop", "customer", "c1", type, data)


show("register", customer("Register", {"email": "ann@example.com", "name": "Ann"}))
show("set password", customer("SetPassword", {"password": "correct horse"}))
show("sign in, wrong password", customer("SignIn", {"password": "wrong horse"}))
show("sign in", customer("SignIn", {"password": "correct horse"}))
print(k.query("shop", "GetCustomer", {"id": "c1"}))
show("erase", customer("Erase"))
# Erased: the customer's data is gone, and with it the right to act.
try:
    k.query("shop", "GetCustomer", {"id": "c1"})
except Rejected as err:
    print(f"read: {err.code}")
rs
// with_domain: the client moves the fields the domain declares personal or secret to the vault.
let me = RequestContext {
    sender_identity: "c1".into(),
    ..Default::default()
};
let kernable = Kernable::new(Options::default().context(me))?.with_domain(&shop().domain);
let customer = |command_type, data: Value| {
    kernable.submit(Submit::new("shop", "customer", "c1", command_type).data(data))
};
let read =
    || kernable.query::<Value>(Query::new("shop", "GetCustomer").data(json!({ "id": "c1" })));

show(
    "register",
    customer(
        "Register",
        json!({ "email": "ann@example.com", "name": "Ann" }),
    )
    .await?,
);
show(
    "set password",
    customer("SetPassword", json!({ "password": "correct horse" })).await?,
);
show(
    "sign in, wrong password",
    customer("SignIn", json!({ "password": "wrong horse" })).await?,
);
show(
    "sign in",
    customer("SignIn", json!({ "password": "correct horse" })).await?,
);
println!("{}", read().await?);
show("erase", customer("Erase", Value::Null).await?);
// Erased: the customer's data is gone, and with it the right to act.
if let Err(Error::Rejected(r)) = read().await {
    println!("read: {}", r.code);
}
text
register: committed
set password: committed
sign in, wrong password: denied (Wrong customer or password)
sign in: committed
{ id: 'c1', email: 'ann@example.com', name: 'Ann' }
erase: committed
read: forbidden
text
register: committed
set password: committed
sign in, wrong password: denied (Wrong customer or password)
sign in: committed
{'id': 'c1', 'email': 'ann@example.com', 'name': 'Ann'}
erase: committed
read: forbidden
text
register: committed
set password: committed
sign in, wrong password: denied (Wrong customer or password)
sign in: committed
{"id":"c1","email":"ann@example.com","name":"Ann"}
erase: committed
read: forbidden

After Erase, the customer's email and name are gone from the vault, in the customer's stream and in every order's confirmation alike. A read model rebuilt from the log reads null where they were. The events themselves stay, and the hash chain still verifies.

Next: 8. Operate.