Supplement · 4 · Security, privacy, accessibility

Three Qualities You Cannot Add Later

Security, privacy and accessibility fail for the same reason: each is treated as a review at the end, when every decision that determines the answer was made months earlier. This supplement runs all three as design activities on one flow, with the artifacts that make them checkable.

Reading ≈ 26 minPractice ≈ 90 min

Mission tie-in: lesson 0043 listed security and accessibility among the returns pilot’s drivers. A driver that never becomes a data-flow diagram, a failing test or a contract shape is a wish.

Why this is here

You reach this page when the pilot is close enough to be real. Someone asks whether the returns flow has had a security review, and the honest answer is that nobody has looked at it as a system — only at individual pull requests. Someone else asks what happens to the free-text return reasons, and the answer is “they’re in the database.” And the accessibility work is a ticket in the backlog called “a11y pass,” scheduled for the week before launch, which is precisely when the contracts that determine the answer can no longer change.

All three are architecture problems disguised as review activities. An object-level authorization defect is a decision about where authorization lives relative to the data boundary. A retention rule is a decision about what the data model records at all. And an accessible error message is a decision about whether your eligibility contract returns a structured refusal reason or an HTTP status code. Each of those decisions gets cheap treatment at design time and expensive treatment at any point after.

Knowledge: threat model the flow, not the feature

A threat-modelling workshop is 90 minutes with the people who know the system, four questions, and a whiteboard. Adam Shostack’s framing is the one to use because it is answerable by a team rather than by a specialist: what are we building? what can go wrong? what are we going to do about it? did we do a good job?

Start with the data-flow diagram, because “what can go wrong” is unanswerable without knowing what crosses which boundary. For the returns flow the table is the diagram — six flows, and the trust-boundary column is what the whole workshop turns on:

Two flows on that list are the ones teams routinely forget. Flow 4 is inbound from a third party and is usually built as “the carrier calls us” without anyone asking who else can. Flow 5 is the internal one — staff access to customer data — which is invisible in every architecture diagram drawn from the customer’s point of view and is where a large share of real privacy incidents live.

Now apply STRIDE to each element: Spoofing, Tampering, Repudiation, Information disclosure, Denial of service, Elevation of privilege. The point of the mnemonic is not completeness; it is that it forces six different questions at each element, so a team does not spend the whole hour on the one threat somebody already had in mind.

Six findings, four of them on flows that never appear in a customer journey map. Notice also that none of the design changes is a security product; they are all ordinary design decisions — where a value is derived rather than supplied, which two facts must agree, where a predicate lives.

Authentication is not authorization

The most common serious defect in an application like this one is not a missing login. It is a login that works perfectly, followed by no check that this user may see that object. OWASP calls it broken object-level authorization, and it is the top item on their API risk list because it is trivially exploitable and invisible in every test written from the happy path.

from dataclasses import dataclass
from typing import Protocol

@dataclass(frozen=True)
class Principal:
    customer_id: str

@dataclass(frozen=True)
class ReturnRequest:
    id: str
    owner_id: str
    order_id: str
    status: str

class ReturnNotFound(Exception):
    """Raised when the return does not exist OR is not the caller's."""

class ReturnRepository(Protocol):
    def get(self, return_id: str) -> ReturnRequest | None: ...
    def get_for_owner(self, return_id: str, customer_id: str) -> ReturnRequest | None: ...

# BEFORE. The session is genuine, so `principal` is a real authenticated
# customer. Nothing here asks whether the return belongs to them:
# RET-8831 becomes RET-8832 and you are reading a stranger's address.
def get_return(principal: Principal, return_id: str, repo: ReturnRepository):
    return repo.get(return_id)

The fix has three parts, and only the first is obvious:

# AFTER.
# 1. Ownership is part of the query, not a check after the fact. A post-fetch
#    `if found.owner_id != principal.customer_id` works until someone adds a
#    second call site; a repository that cannot return another owner's row does not.
# 2. The same error for missing and for forbidden, so the endpoint is not an
#    oracle telling an attacker which return ids exist.
# 3. The denial is logged with the principal, because a burst of them is the
#    highest-signal detection you will get for free.
def get_return(principal: Principal, return_id: str, repo: ReturnRepository) -> ReturnRequest:
    found = repo.get_for_owner(return_id, principal.customer_id)
    if found is None:
        audit.denied(actor=principal.customer_id, resource=return_id)
        raise ReturnNotFound(return_id)
    return found

And the test that keeps it fixed. A negative acceptance example is an abuse case written in the same form as a feature example, so it lives in the normal suite and fails the build rather than sitting in a security report:

def test_a_customer_cannot_read_another_customers_return(repo):
    alice = Principal("cust-1")
    mallory = Principal("cust-2")
    ret = repo.create(owner_id="cust-1", order_id="ord-77")

    with pytest.raises(ReturnNotFound):
        get_return(mallory, ret.id, repo)

    assert get_return(alice, ret.id, repo).id == ret.id

Multi-tenant isolation: make the predicate structural

The Storefront monolith serves three brands from one database, and the returns store inherits that. “Every query filters by brand” is a convention, and conventions are one hurried pull request away from a cross-brand disclosure. Set the scope once, where the request is authenticated, and let the data layer carry it:

class BrandScope:
    """Brand isolation is a property of the connection, not of each query.

    Set once at the composition root from the authenticated principal. Every
    statement on this session then carries the predicate, so a forgotten
    WHERE clause cannot cross a brand boundary -- it returns nothing instead.
    """

    def __init__(self, session, brand_id: str) -> None:
        self._session = session
        self._brand_id = brand_id

    def __enter__(self):
        self._session.execute(
            "SET LOCAL app.current_brand = :brand", {"brand": self._brand_id}
        )
        return self._session

    def __exit__(self, exc_type, exc, tb) -> None:
        if exc_type is None:
            self._session.commit()
        else:
            self._session.rollback()

Underneath, the database enforces it with a row-level policy comparing the row’s brand to app.current_brand. Above it, an architecture fitness function fails the build if any repository opens a session outside BrandScope. Three layers — a policy that cannot be bypassed, a scope that is set once, and a test that catches the bypass attempt — and none of them depends on a reviewer noticing.

Privacy by design: the retention table is part of the data model

The pilot carries a constraint from lesson 0045: free-text return notes are deleted 30 days after the return closes. A constraint like that is either a property of the schema or it is a paragraph in a policy document that nobody implements. Making it real starts with a table that has a purpose column, because purpose is what justifies collection at all — and several rows do not survive being asked for one.

Row two is the design move worth copying. The carrier needs a name and an address; the returns service does not need to keep them. Reading them at label time and never persisting them removes an entire class of retention, deletion, breach and access-control work — the cheapest privacy control available is the field you decided not to store. That is a data-model decision, and it is unavailable once six months of production rows exist.

Note also what a deletion requirement does to the schema. If the note column were NOT NULL, the 30-day rule would force either a row deletion (which destroys the financial record beside it) or a sentinel value (which lies). Splitting customer free text from the operational record is what makes the retention rule expressible at all. Retention is a modelling constraint, not a cleanup job.

Accessibility is an architecture driver, not a CSS pass

The pilot commits to WCAG 2.2 AA on the critical flows. Most of that commitment is front-end work, and a specific, load-bearing minority of it is not — it constrains contracts, state and infrastructure, which means it must be decided now:

Then put it in the pipeline, at three levels, because the levels catch different things:

1. Automated, every build: an accessibility linter over the five critical journey pages, failing the build on serious and critical violations. This catches missing labels, contrast and structure — a genuine floor, and nothing more. Automated tools cannot evaluate whether an error message is useful or whether focus order makes sense.
2. Keyboard-only walkthrough, every release: one person completes a return without touching a mouse. Fifteen minutes, and it finds the class of defect that no linter reaches.
3. Screen-reader pass on the two critical flows, before the 1% rollout gate — wired into the rollout contract from lesson 0049 as an entry condition, so it cannot be skipped by being busy.

When this is the wrong move

• The system holds no data anyone wants and has no users but you. An internal batch tool with three operators does not need a 90-minute STRIDE session. Spend twenty minutes on the two flows that cross a trust boundary and stop.
• Threat modelling before the design exists. Run it when there is a data-flow diagram to argue with. Held too early it produces a generic list — “consider encryption” — that changes no decision and inoculates the team against doing it properly later.
• Isolating tenants that are not really tenants. If “brands” are three internal teams with the same data-access rights, a row-level policy adds operational complexity and buys nothing. Confirm the isolation is a real requirement before making it structural.
• Retaining more because deletion is hard. The reflex when a retention rule is awkward is to widen it. If the purpose column is empty, the right change is to stop collecting — not to keep it longer under a vaguer justification.
• Full WCAG conformance on an internal admin screen with four users, this week. Prioritise the critical customer flows, and be explicit that the admin surface is a stated gap with a date — rather than pretending the whole product is AA.
• Blocking a release on a finding nobody has ranked. A threat list without likelihood and impact becomes a queue that stops delivery and trains people to route around the workshop. Rank, decide what you accept, and record the acceptance with an owner.

Skill: find the real defect

Practice: run the workshop on your own system

1. Draw six flows. For one workflow you own, list the flows and mark every trust boundary. Force yourself to include one inbound third-party call and one staff-access path; those are the two that get skipped.
2. Run 90 minutes of STRIDE with two or three colleagues. One threat per element per letter, timeboxed. Record: threat, existing control, design change, owner. A workshop that produces no design change either found nothing or was not honest.
3. Rank and accept. Score each finding by likelihood and impact. Fix the top three, and explicitly record acceptance — with an owner and a revisit date — for the rest. An unranked list stops delivery and gets ignored.
4. Write one negative acceptance test. Take your worst authorization finding and express it as a test in your normal suite, in the same style as a feature example. It must fail before the fix and pass after.
5. Build the data inventory with a purpose column. Every row without a purpose is a deletion candidate. For one of them, work out what it would cost to stop collecting it today — that number is usually smaller than expected and only grows.
6. Pick the three WCAG criteria that constrain your contracts, not your CSS. Write the evidence mechanism for each, and add one of them to a release gate so it cannot be deferred by being busy.

Read deeper

• Threat Modeling: Designing for Security, Adam Shostack — ch. 1 on the four questions, ch. 3 on STRIDE per element. The OWASP Threat Modeling Cheat Sheet is the short field version.
• OWASP API Security Top 10 · Broken Object Level Authorization — the defect above, ranked first, with test guidance.
• OWASP ASVS — a requirements catalogue you can select a level from and turn into acceptance criteria; and the OWASP Top 10 for the risk framing.
• WCAG 2.2 and the How to Meet WCAG quick reference — filter to AA and read the four criteria new in 2.2; three of them constrain architecture.
• Release It!, Michael Nygard — ch. 4–5 on stability patterns, and ch. 11 on security in production: the operational half of everything above.
• Building Secure and Reliable Systems, Adkins et al. (Google, free online) — least privilege, blast-radius reduction and the argument for structural rather than procedural controls.
• Course: lesson 0045 (contracts, PII lifecycle), lesson 0043 (security and operability as drivers), lesson 0049 (release gates). Reference: fitness function, blast radius.

Ask your agent-teacher to attack your data-flow table one letter of STRIDE at a time — and to say, for each suggested control, which future pull request could quietly remove it.