coreci/atelier
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 28 Wiki Activity

docs(P5): complete examples + cross-links phase

Browse Source 
---ci---
project: atelier
phase: 5
milestone: v0.3
status: complete
requirements:
  covered: [ATELIER-86, ATELIER-87, ATELIER-88]
  partial: []
---/ci---
This commit is contained in:
Jon Chery
2026-08-05 03:40:37 +00:00
parent 648fcb5d85
commit 4c8700e5a4
5 changed files with 839 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files
examples/bad/compliance-audit-log.md
+222
View File
@@ -0,0 +1,222 @@
# Bad Example: Compliance Audit Log (Two Breaches)
> An audit logging implementation that violates **two** Atelier
> compliance principles in one example (per IDEATE-26, D-044):
> **P1** (Audit Logs are Append-Only) — a mutable audit log with
> routine `DELETE`/`UPDATE` "cleanup" — and **P9** (Secrets and
> Sensitive Data are Redacted in Audit) — a database password leaked
> into an audit record. Each violation is cited, then fixed.
## The Code
```python
# audit_log.py — the audit sink, stored in a mutable Postgres table
import psycopg2, datetime
# P1 VIOLATION: the audit log is a regular mutable table. There is no
# write-once protection, no immutable bucket, no hash-chaining.
# Any DB user with UPDATE/DELETE can rewrite history.
CREATE_TABLE = """
CREATE TABLE audit_log (
id BIGSERIAL PRIMARY KEY,
timestamp TIMESTAMPTZ NOT NULL,
event TEXT NOT NULL,
actor TEXT NOT NULL,
target TEXT,
payload JSONB,
request_id TEXT
);
-- No row-level immutability. No trigger preventing UPDATE/DELETE.
"""
def write_event(event, actor, target=None, payload=None, request_id=None):
conn = psycopg2.connect(os.environ["DATABASE_URL"])
conn.execute(
"INSERT INTO audit_log (timestamp, event, actor, target, payload, request_id) "
"VALUES (%s, %s, %s, %s, %s, %s)",
(datetime.datetime.utcnow(), event, actor, target,
json.dumps(payload), request_id),
)
# P1 VIOLATION (continued): "cleanup" that mutates the audit log.
# A routine job deletes records older than 30 days to "save space"
# and updates records to "fix typos in the actor field."
def cleanup_audit_log():
conn = psycopg2.connect(os.environ["DATABASE_URL"])
# DELETE — an audit record is destroyed. This is tampering,
# dressed as housekeeping.
conn.execute("DELETE FROM audit_log WHERE timestamp < NOW() - INTERVAL '30 days'")
# UPDATE — an audit record is rewritten. The "fix" is the
# violation; the original actor is lost.
conn.execute("UPDATE audit_log SET actor = 'admin' WHERE actor LIKE 'svc-%'")
```
```python
# The call site that leaks a secret into the audit log.
def read_config(key):
# ... fetches a secret from the secrets manager ...
value = secrets_manager.get(key) # e.g. the raw DB password
# P9 VIOLATION: the raw secret value is written into the audit
# payload. The append-only log is now a secret store.
write_event(
event="config.read",
actor="api-server",
target={"kind": "secret", "id": key},
payload={"value": value}, # <- the secret, in plaintext
request_id=req.id,
)
return value
```
The resulting audit record:
```json
{
"id": 48213,
"timestamp": "2026-08-05T09:12:03Z",
"event": "config.read",
"actor": "api-server",
"target": {"kind": "secret", "id": "db-password"},
"payload": {"value": "p@ssw0rd-sup3r-s3cr3t-plaintext"},
"request_id": "req_91c2"
}
```
A week later, the `cleanup_audit_log` job `DELETE`s this record (it
is older than 30 days in the team's "retention" — which is actually a
storage-economy decision, not a policy), and `UPDATE`s every
`svc-*` actor to `admin`. The secret was in the log for a week,
readable by anyone with `SELECT` on the table; now the record of it
having been there is gone.
## What Makes It Bad
### Breach 1 — Mutable Audit Log (Compliance P1 Audit Logs are Append-Only)
- The audit log is a regular mutable Postgres table. `DELETE FROM
audit_log WHERE timestamp < ...` and `UPDATE audit_log SET actor =
...` both succeed. The log is a draft, not a record.
- Routine `DELETE` as "cleanup" is the cardinal P1 violation: the
deletion of an audit record is itself an auditable incident, not a
housekeeping task. "We deleted old records to save space" is a P3
(Retention is Policy, Not Storage) violation *and* a P1 violation —
the retention decision is driven by storage cost, and the
mechanism is tampering.
- The `UPDATE` that rewrites `svc-deploy` → `admin` destroys
attribution (a P7 violation stacked on the P1 violation): the
original actor is lost, and the replacement (`admin`) is a shared
identity that could be any of ten engineers.
- **Fix:** the audit sink is append-only *by construction*, not by
policy. Write-once storage (WORM bucket, immutable log stream,
hash-chained ledger) enforces immutability at the substrate.
Retention is a declared policy with a meta-audit of deletions; a
human does not run ad-hoc `DELETE` jobs.
```python
# Fix: write to an append-only sink (illustrative — S3 Object Lock,
# WORM bucket, or a hash-chained ledger). The API has no update /
# delete path; the storage refuses mutation.
def write_event(event, actor, target=None, payload=None, request_id=None):
record = {
"timestamp": datetime.datetime.now(datetime.timezone.utc).isoformat(),
"event": event,
"actor": actor, # the authenticated principal, not "admin"
"target": target,
"payload": redact(payload), # see Breach 2 fix
"request_id": request_id,
"prev_hash": last_hash(), # hash-chaining: tampering breaks the chain
}
record["hash"] = sha256(canonical_json(record))
append_only_sink.write(record) # WORM storage; no update/delete API exists
# Fix: retention is a declared, reviewed policy — not an ad-hoc DELETE.
# When an audit segment ages out, the deletion is itself meta-audited
# in a higher-tier log with the rule that authorized it.
# (See domains/compliance/data-retention.md and audit-logs.md.)
```
- See `domains/compliance/audit-logs.md` (Audit Logs are Append-Only)
and `domains/compliance/first-principles.md` P1.
### Breach 2 — Secret Leaked in Audit Log (Compliance P9 Secrets and Sensitive Data are Redacted in Audit)
- `payload={"value": value}` writes the raw DB password into the
audit record. The append-only log is now a secret store: anyone
with `SELECT` on `audit_log` can read production credentials. The
log is harder to secure than the secrets manager it read from.
- Once the secret is in an append-only log, the remediation is
expensive — rotate the secret *and* rewrite the log's access scope
(you cannot edit the record; it is append-only). Redaction must
happen *at the logging boundary, before the record is written*, not
by opportunistic scrubbing after the fact.
- The redaction policy here is "nothing" — there is no rule for
which fields are redacted, by what mechanism, in which event type.
A redaction rule that lives in no one's head and no code is a P9
violation waiting to happen (and it happened).
- **Fix:** redaction is structural, applied at the logging boundary
before the record reaches the append-only sink. The policy is
itself auditable (which fields, by what rule, in which event).
```python
# Fix: redaction at the boundary. Log the FACT of the action
# (a secret was read), never the CONTENT of the secret.
REDACTED_FIELDS = {"value", "token", "password", "authorization", "secret"}
def redact(payload):
if not isinstance(payload, dict):
return "[REDACTED:non-object]"
out = {}
for k, v in payload.items():
if k.lower() in REDACTED_FIELDS or "secret" in k.lower():
out[k] = "[REDACTED:secret]"
else:
out[k] = v
out["_redaction"] = "secret-value-policy/v1" # the rule is auditable
return out
# The fixed audit record:
# {
# "event": "config.read",
# "actor": "api-server", # the authenticated principal
# "target": {"kind": "secret", "id": "db-password"},
# "payload": {"value": "[REDACTED:secret]"},
# "_redaction": "secret-value-policy/v1",
# "request_id": "req_91c2"
# }
# The fact of the read is logged; the secret never enters the log.
```
- See `domains/compliance/audit-logs.md` (Redaction at the Boundary)
and `domains/compliance/first-principles.md` P9. Cross
`domains/security/secrets.md` — the audit-side redaction is the
complement of secret management.
## The Cascade (Two Breaches Compound)
The two violations compound destructively. The secret enters the
mutable log (P9 breach), where it sits readable by any `SELECT`-holder
for a week. Then the `cleanup` job `DELETE`s the record (P1 breach) —
destroying the evidence that the secret was ever logged, while the
secret itself has already been exposed to every reader of the table.
The `UPDATE` that rewrites `svc-deploy` → `admin` (a P7 attribution
breach stacked on the P1 breach) means that even if a copy of the
record survived, the actor who triggered the secret read is no longer
identifiable. The team cannot answer "who read the DB password and
when" — the log that would answer it was mutated, and the secret it
leaked is now in the wild. This is the worst-case interaction of P1
and P9: a secret leak with no attributable actor and no surviving
record.
## Cross-Domain Links
- `domains/compliance/audit-logs.md` — the append-only guarantee and
the redaction-at-boundary rule this code violates.
- `domains/compliance/first-principles.md` — P1 (Append-Only) and P9
(Redacted) are the two breached principles; P7 (Attributable) is
breached by the `UPDATE` rewrite.
- `domains/compliance/evidence.md` — an audit log that can be
`DELETE`d is not admissible evidence; the append-only guarantee is
what makes it admissible.
- `domains/compliance/data-retention.md` — retention is a declared
policy with meta-audited deletions, not an ad-hoc `DELETE` job.
- `domains/security/secrets.md` — redaction at the logging boundary
is the audit-side complement of secret management.
- `domains/observability/logging.md` — audit logs are structured
logging with an append-only guarantee; the logging primitives
compose here.
examples/bad/i18n-string-concat.md
+175
View File
@@ -0,0 +1,175 @@
# Bad Example: i18n String Concatenation
> A checkout component that violates Atelier's i18n principles. Each
> violation is cited, then fixed.
## The Code
```typescript
// Checkout.tsx — the cardinal i18n violation
function CartSummary({ itemCount, name, total, currency, date }) {
// P3 VIOLATION: inline string concatenation. The source-language
// word order ("Welcome, {name}! You have {n} items") is baked into
// code. Every locale with different word order is broken.
const welcome = "Welcome, " + name + "!";
// P4 VIOLATION: hand-rolled plural branching. `if (n === 1)` encodes
// exactly English's one/other rule. Arabic (six categories), Russian
// (three), Polish (three) are all wrong.
const items =
itemCount === 1 ? "1 item" : itemCount + " items";
// P5 VIOLATION: hand-rolled currency + date formatting. "$" + total
// is wrong for de-DE (symbol, grouping, placement). The date
// `getMonth() + 1 + "/" + getDay()` is US-only (mm/dd/yyyy).
const price = "$" + total.toFixed(2);
const d = new Date(date);
const dateStr = (d.getMonth() + 1) + "/" + d.getDate() + "/" + d.getFullYear();
return (
<div>
<h1>{welcome}</h1>
<p>{items} · {price} · {dateStr}</p>
</div>
);
}
```
```typescript
// The "resource" file — a custom CSV the team hand-rolled.
// locale,en_us
// welcome_prefix,Welcome,
// item_singular,item
// item_plural,items
//
// This is a P3 violation on its own: a custom format no standard
// tool (xgettext, i18next, FormatJS) can extract from or compose with.
```
The team runs their first i18n test against real Arabic translations —
after the string freeze, after the translator was paid. The Arabic
build renders `"Welcome, محمد!"` with the name on the wrong side of
the comma, `"1 items"` for a single item (Arabic has six plural
categories, not two), and the price as `"$1,234.56"` (Arabic-Egypt
formats as `"١٬٢٣٤٫٥٦ ج.م.‏"`). Every screen is a rewrite, not a patch.
## What Makes It Bad
### Inline String Concatenation (i18n P3 Resources are External, Not Inline)
- `"Welcome, " + name + "!"` bakes English word order into code. In
Japanese the name comes first (`ようこそ、محمدさん！`); in Arabic the
structure differs again. The concatenation is invisible to the
extraction pipeline (`xgettext`, `i18next-parser`) — the translator
never sees it as a unit, and the string cannot be versioned or
rolled back as a whole.
- The custom `.csv` "resource" store is a second P3 violation: no
standard tool reads it, it carries no plural grammar, and it cannot
compose with the ICU formatting layer.
- **Fix:** strings live in a standard locale resource file, addressed
by key. Code calls `t("welcome", { name })`; the resource carries
the parameterized message.
```json
// en-US.json (ICU MessageFormat)
{
"checkout.welcome": "Welcome, {name}!",
"checkout.cart.summary": "{count, plural, one {# item} other {# items}} · {price} · {date}"
}
```
```json
// ar-EG.json — six plural categories per CLDR; the code is identical
{
"checkout.welcome": "أهلاً بك، {name}!",
"checkout.cart.summary": "{count, plural, zero {لا عناصر} one {عنصر واحد} two {عنصران} few {# عناصر} many {# عنصرًا} other {# عنصر}} · {price} · {date}"
}
```
- See `domains/i18n/locale-resources.md` (Resources are the Boundary)
and `domains/i18n/first-principles.md` P3.
### Hand-Rolled Plural Branching (i18n P4 Plural and Gender are Parameterized)
- `itemCount === 1 ? "1 item" : itemCount + " items"` encodes
English's one/other rule and nothing else. Arabic has six
categories (zero, one, two, few, many, other); Russian has three
(one, few, many); Polish has three with different boundaries. A
two-branch `if` is a C1 (Correctness) violation masquerading as a
shortcut — it returns a wrong answer for every non-English locale.
- **Fix:** the count goes to ICU MessageFormat; the formatter
consults `Intl.PluralRules` for the active locale; the resource
carries the variant for that category. The code passes the count,
nothing more.
```typescript
// The code passes the count; the resource + formatter pick the form.
t("checkout.cart.summary", { count: itemCount, price, date });
// Intl.PluralRules("ar-EG").select(1) === "one" -> "عنصر واحد"
// Intl.PluralRules("ar-EG").select(2) === "two" -> "عنصران"
// Intl.PluralRules("ar-EG").select(5) === "few" -> "٥ عناصر"
```
- See `domains/i18n/locale-resources.md` (Plural and Gender in
Resources) and `domains/i18n/formatting.md` (Plural Rules).
### Hand-Rolled Currency and Date Formatting (i18n P5 Formatting is Locale-Aware)
- `"$" + total.toFixed(2)` hardcodes the US dollar symbol, US
grouping (`,`), and US placement (symbol before the number). In
`de-DE` the euro formats as `"1.234,56 €"` (symbol after, dot
grouping). In `ar-EG` the pound formats as `"١٬٢٣٤٫٥٦ ج.م.‏"`
(Arabic-Indic digits, different grouping).
- `(d.getMonth() + 1) + "/" + d.getDate() + "/" + d.getFullYear()`
produces `11/7/2024` — US `mm/dd/yyyy`. Most of the world reads
`dd/mm/yyyy`; ISO is `yyyy-mm-dd`. A hand-rolled date formatter
encodes one locale's convention and silently produces wrong output
for every other.
- **Fix:** `Intl.NumberFormat` and `Intl.DateTimeFormat` with a BCP
47 locale tag. CLDR is the source of truth; `Intl` is the runtime.
```typescript
new Intl.NumberFormat("ar-EG", { style: "currency", currency: "EGP" })
.format(1234.56); // "١٬٢٣٤٫٥٦ ج.م.‏"
new Intl.DateTimeFormat("ar-EG", { dateStyle: "medium" })
.format(new Date(date)); // "٧ نوفمبر ٢٠٢٤"
```
- See `domains/i18n/formatting.md` (the Intl surface, dates, numbers,
currencies) and `domains/i18n/first-principles.md` P5.
### Source Language Treated as the Default (i18n P1 Source Language is a Locale)
- The component has no resource layer at all for the source locale —
English is "just the strings in the code." When the first second
locale arrives, the fix is a rewrite (extract every string,
restructure every concatenation), not a patch. The source language
is `en-US`, a locale among many — it is not `null`.
- **Fix:** extract source strings into `en-US.json` from day one,
even before a second locale exists. The resource layer is the
boundary from the first commit.
- See `domains/i18n/first-principles.md` P1 and
`domains/uiux/copywriting.md`.
## The Cascade
The violations compound. Inline concatenation makes strings invisible
to the extraction pipeline, so the translator never receives them as
units — they reconstruct them by reading the code. Hand-rolled
plurals return wrong answers for every non-English locale, so the
Arabic build ships `"1 items"` for a single item. Hand-rolled
formatting produces US-shaped output everywhere, so the price and
date are wrong for `de-DE`, `ar-EG`, `zh-Hans-CN`, and every other
locale. And because the first i18n test ran against real translations
(a P8 violation — pseudo-locales should have surfaced all of this
while the fix was still cheap), the defects are found after the
string freeze, after the translator was paid, and after the release
date was promised. The fix is now a re-translation and a re-release,
not a commit.
## Cross-Domain Links
- `domains/i18n/locale-resources.md` — the resource layer this code
lacks; the standard formats (`.po`, JSON, Fluent, ICU Resource
Bundle) it should have used.
- `domains/i18n/formatting.md` — the `Intl`/ICU/CLDR formatting this
code should call instead of hand-rolling.
- `domains/i18n/first-principles.md` — P3, P4, P5, and P8 (pseudo-
locales test early).
- `domains/uiux/copywriting.md` — copy lives in resources, not in
code.
- `domains/api/error-responses.md` — the same parameterized-message
discipline applies to localized API errors.