Appearance
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(), ¶ms, &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_readlists 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_eraselists 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"] = Noners
// 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: forbiddentext
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: forbiddentext
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: forbiddenAfter 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.
