refactor: lay the repository out by role

local/ held six unrelated things under a name that stopped being true once it
became the production runtime: the service, the frontend, the tests, the ops
commands, the container definitions and the dependency lock, 65 files with
nothing to tell them apart.

  app/      the service: api/ routers, core/ for identity, database, models,
            prices and secret loading, and the worker, bootstrap and schema
  tests/    the twelve suites, no longer inside the shipped package
  ops/      backup, readiness, dependency audit, security summary
  infra/    Dockerfiles, gateway templates, ClamAV and storage configuration,
            the requirements and their hash lock
  web/      the Site, Kanban and portal pages with their scripts

deploy/Dockerfile.api now copies app/ alone, so the tests stop shipping to
production; the local image still carries them, because the suites run inside
the stack's network.

Five kinds of reference had to follow, and each was found by something different
rather than by reading. Imports of the form "from . import db" survived a rewrite
that only matched "from .db import". Tests kept relative imports of modules that
had left the package. A mock.patch target names its module in a string, where no
import rewriting can see it. The browser test resolves a fixture by path. And the
release gate's markers pointed at local/runtime.py and local/worker.py, which is
the decay its new marker test exists to catch — it caught it.

Verified from docker compose down -v: the stack starts, all six integration
suites, both browser suites and the twenty-nine unit tests pass.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

app/core/__init__.py

@@ -0,0 +1 @@
+"""Shared foundations: identity, database, models, prices, secret loading."""

app/core/auth.py

@@ -0,0 +1,111 @@
+"""Local customer passwords and revocable database sessions. No email service."""
+import hashlib
+import os
+import secrets
+import logging
+import json
+from uuid import UUID, uuid4
+from fastapi import HTTPException, Request
+from ..core.db import connect
+
+COOKIE_SECURE = os.environ.get('COOKIE_SECURE', 'false').lower() == 'true'
+
+def client_ip(request: Request):
+    """The requester's address, for rate-limit buckets and security events.
+
+    The API is only reachable through the web gateway, which replaces
+    X-Forwarded-For with the peer address it observed, so the header carries
+    exactly one value the client could not choose. Without this every request
+    looks like the gateway, which collapses per-source limits into one global
+    bucket and strips the address from the audit trail.
+    """
+    forwarded = request.headers.get('x-forwarded-for', '').split(',')[0].strip()
+    if forwarded:
+        return forwarded[:64]
+    return request.client.host if request.client else 'unknown'
+
+def password_hash(password, salt=None):
+    salt = salt or secrets.token_hex(16)
+    digest = hashlib.scrypt(password.encode(), salt=bytes.fromhex(salt), n=16384, r=8, p=5).hex()
+    return f'scrypt-v2${salt}${digest}'
+
+def password_matches(password, stored):
+    try:
+        version, salt, digest = stored.split('$')
+        if version not in ('scrypt', 'scrypt-v2'): return False
+        actual = hashlib.scrypt(password.encode(), salt=bytes.fromhex(salt), n=16384, r=8,
+                                p=1 if version == 'scrypt' else 5).hex()
+        return secrets.compare_digest(actual, digest)
+    except (ValueError, TypeError):
+        return False
+
+DUMMY_PASSWORD_HASH = password_hash('invalid-account-password', '00'*16)
+
+def session_row(request):
+    try:
+        sid = UUID(request.cookies.get('dtf_session', ''))
+    except ValueError:
+        raise HTTPException(401, 'Start a local session first')
+    with connect() as c:
+        row = c.execute('SELECT * FROM dtf_local.sessions WHERE id=%s AND expires_at>now()', (sid,)).fetchone()
+    if not row:
+        raise HTTPException(401, 'Session expired; sign in or start a new session')
+    return row
+
+def owner(request: Request):
+    return session_row(request)['owner']
+
+def new_session(c, response, identity=None):
+    sid = uuid4()
+    identity = identity or uuid4()
+    c.execute('INSERT INTO dtf_local.sessions(id,owner) VALUES(%s,%s)', (sid,identity))
+    response.set_cookie('dtf_session', str(sid), httponly=True, secure=COOKIE_SECURE,
+                        samesite='strict', max_age=86400*7)
+    return identity
+
+def transfer_guest(c, previous, identity):
+    # Successful authentication can claim only the current guest browser's records.
+    if c.execute('SELECT id FROM dtf_local.accounts WHERE id=%s', (previous['owner'],)).fetchone():
+        return
+    for table in ('uploads','quotes','orders'):
+        c.execute(f'UPDATE dtf_local.{table} SET owner=%s WHERE owner=%s', (identity,previous['owner']))
+    c.execute('DELETE FROM dtf_local.sessions WHERE owner=%s', (previous['owner'],))
+
+def audit(event, **fields):
+    # Only explicit metadata: never cookies, passwords, signed URLs or request bodies.
+    logging.getLogger('dtf.security').warning(json.dumps({'event':event, **fields}, sort_keys=True))
+    try:
+        from psycopg.types.json import Jsonb
+        with connect() as c:
+            c.execute('INSERT INTO dtf_local.security_events(event,details) VALUES(%s,%s)',(event,Jsonb(fields)))
+    except Exception:
+        # Logging must still work during a DB outage without recursively auditing itself.
+        logging.getLogger('dtf.security').error('Security event persistence unavailable')
+
+def rate_limit(scope, identity, limit, seconds=900):
+    key = hashlib.sha256((scope+'|'+identity).encode()).hexdigest()
+    with connect() as c:
+        row = c.execute("""INSERT INTO dtf_local.login_attempts(key,attempts) VALUES(%s,1)
+          ON CONFLICT(key) DO UPDATE SET
+          attempts=CASE WHEN dtf_local.login_attempts.started_at < now()-%s*interval '1 second' THEN 1 ELSE LEAST(dtf_local.login_attempts.attempts+1,1000000) END,
+          started_at=CASE WHEN dtf_local.login_attempts.started_at < now()-%s*interval '1 second' THEN now() ELSE dtf_local.login_attempts.started_at END
+          RETURNING attempts""", (key,seconds,seconds)).fetchone()
+    if row['attempts'] > limit:
+        audit('rate_limit', scope=scope)
+        raise HTTPException(429, 'Too many requests. Try again later.', headers={'Retry-After':str(seconds)})
+
+def throttle(email, request):
+    # Independent account and source buckets prevent bypass by rotating emails.
+    rate_limit('auth-source', client_ip(request), 60)
+    rate_limit('auth-account', email, 10)
+
+def operator(request: Request):
+    token = request.cookies.get('dtf_operator', '')
+    if not token or len(token)>128:
+        raise HTTPException(401, 'Sign in to the local Kanban')
+    digest = hashlib.sha256(token.encode()).hexdigest()
+    with connect() as c:
+        row = c.execute('SELECT username FROM dtf_local.operator_sessions WHERE token_hash=%s AND expires_at>now()', (digest,)).fetchone()
+    if not row:
+        raise HTTPException(401, 'Operator session expired')
+    return row['username']

app/core/db.py

@@ -0,0 +1,23 @@
+import os
+from pathlib import Path
+import psycopg
+from psycopg.rows import dict_row
+
+def connect():
+    # Production passes credentials as discrete libpq fields.  This avoids
+    # treating characters in a generated password as URL syntax.  Local and
+    # test environments retain DATABASE_URL compatibility.
+    if os.environ.get('DATABASE_HOST'):
+        return psycopg.connect(
+            host=os.environ['DATABASE_HOST'],
+            dbname=os.environ['DATABASE_NAME'],
+            user=os.environ['DATABASE_USER'],
+            password=os.environ['DATABASE_PASSWORD'],
+            row_factory=dict_row,
+        )
+    return psycopg.connect(os.environ['DATABASE_URL'], row_factory=dict_row)
+
+def initialize():
+    with connect() as c:
+        # The schema lives at the package root, one level up from core/.
+        c.execute((Path(__file__).resolve().parent.parent / 'schema.sql').read_text())

app/core/models.py

@@ -0,0 +1,109 @@
+import re
+from decimal import Decimal
+from typing import Literal
+from uuid import UUID
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+class StrictModel(BaseModel):
+    model_config = ConfigDict(extra='forbid', allow_inf_nan=False)
+
+class Customer(StrictModel):
+    cnpj: str
+    zap: str
+    mail: str = Field(max_length=254)
+
+    @field_validator('cnpj')
+    @classmethod
+    def cnpj_valid(cls, value):
+        digits = re.sub(r'\D', '', value)
+        if len(digits) != 14 or len(set(digits)) == 1 or not digits.isascii():
+            raise ValueError('Invalid CNPJ')
+        def check(base, weights):
+            rem = sum(int(n) * w for n,w in zip(base, weights)) % 11
+            return 0 if rem < 2 else 11-rem
+        if check(digits[:12], [5,4,3,2,9,8,7,6,5,4,3,2]) != int(digits[12]) or check(digits[:13], [6,5,4,3,2,9,8,7,6,5,4,3,2]) != int(digits[13]):
+            raise ValueError('Invalid CNPJ')
+        return digits
+
+    @field_validator('zap')
+    @classmethod
+    def phone_valid(cls, value):
+        digits = re.sub(r'\D', '', value)
+        if len(digits) not in (10,11) or not digits.isascii():
+            raise ValueError('Invalid phone')
+        return digits
+
+    @field_validator('mail')
+    @classmethod
+    def email_valid(cls, value):
+        if not re.fullmatch(r'[^\s@]+@[^\s@]+\.[a-zA-Z]{2,}', value.strip()):
+            raise ValueError('Invalid email')
+        return value.strip()
+
+class Freight(StrictModel):
+    service: Literal['pickup','mock-standard'] = 'pickup'
+    postal_code: str = Field(default='', max_length=8)
+
+class UploadStart(StrictModel):
+    name: str = Field(min_length=1, max_length=200, pattern=r'^[^/\\\x00-\x1f]+$')
+    size: int = Field(gt=0, strict=True)
+
+    @field_validator('name')
+    @classmethod
+    def artwork_extension(cls, value):
+        # Union of existing Site product formats; this is NOT malware/pre-flight validation.
+        if not re.search(r'\.(png|jpe?g|webp|tiff?|pdf|psd|psb|ai|cdr)$', value, re.I):
+            raise ValueError('Unsupported artwork file extension')
+        return value
+
+class Item(StrictModel):
+    mode: Literal['file','avulsa','uvfile','uv']
+    metres: Decimal = Field(gt=0, le=12000)
+    grade: int = Field(ge=0, le=100, strict=True)
+    uploads: list[UUID] = Field(min_length=1, max_length=20)
+
+class QuoteRequest(StrictModel):
+    request_key: UUID
+    customer: Customer
+    items: list[Item] = Field(min_length=1, max_length=30)
+    freight: Freight
+
+class Review(StrictModel):
+    items: list[Item] = Field(min_length=1, max_length=30)
+
+class Pay(StrictModel):
+    quote_id: UUID
+
+class Move(StrictModel):
+    state: Literal['rec','tra','fil','imp','cor','fin']
+    version: int = Field(ge=0)
+    reason: str = Field(default='', max_length=1000)
+
+class Register(StrictModel):
+    customer: Customer
+    password: str = Field(min_length=12, max_length=128)
+
+class Login(StrictModel):
+    email: str = Field(min_length=3, max_length=254)
+    password: str = Field(min_length=1, max_length=128)
+
+class OperatorLogin(StrictModel):
+    email: str = Field(min_length=3, max_length=254)
+    password: str = Field(min_length=1, max_length=128)
+
+    @field_validator('email')
+    @classmethod
+    def operator_email_valid(cls, value):
+        value = value.strip().lower()
+        if not re.fullmatch(r'[^\s@]+@[^\s@]+\.[a-zA-Z]{2,}', value):
+            raise ValueError('Invalid email')
+        return value
+
+class FileReference(StrictModel):
+    upload_id: UUID
+    item_index: int = Field(ge=0, strict=True)
+
+class ArtworkSubmission(StrictModel):
+    version: int = Field(ge=0, strict=True)
+    files: list[FileReference] = Field(min_length=1, max_length=60)
+    note: str = Field(min_length=1, max_length=1000)

app/core/pricing.py

@@ -0,0 +1,27 @@
+"""Exact approved Site DTF price ladders; integer BRL cents at the boundary.
+
+Quantity/grade must be supplied by an authenticated commercial reviewer.
+This module does not inspect artwork or perform pre-flight.
+"""
+from decimal import Decimal, ROUND_CEILING
+
+TIERS = {
+    'file': [(90,1490),(75,1620),(60,1750),(40,1870),(0,1990)],
+    'avulsa': [(90,2490),(75,2620),(60,2750),(40,2870),(0,2990)],
+    'uvfile': [(90,6990),(75,7390),(60,7790),(40,8190),(0,8590)],
+    'uv': [(90,8390),(75,8790),(60,9190),(40,9590),(0,9990)],
+}
+
+def price(mode: str, metres: str, grade: int) -> dict:
+    length = Decimal(str(metres))
+    if mode not in TIERS or not length.is_finite() or not 0 < length <= 12000:
+        raise ValueError('Invalid product or length')
+    if isinstance(grade, bool) or not isinstance(grade, int) or not 0 <= grade <= 100:
+        raise ValueError('Grade must be an integer between 0 and 100')
+    billed = max(Decimal('1'), (length * 10).to_integral_value(rounding=ROUND_CEILING) / 10)
+    unit = next(cents for minimum, cents in TIERS[mode] if grade >= minimum)
+    return {'mode': mode, 'metres': str(length), 'grade': grade,
+            'billed_metres': str(billed), 'unit_cents': unit,
+            'total_cents': int(billed * unit),
+            'discount_cents': int(billed * (TIERS[mode][-1][1] - unit))}
+

app/core/secrets.py

@@ -0,0 +1,76 @@
+"""Resolve Docker secret files into the environment before configuration is read.
+
+Swarm mounts each secret as a file and the stack passes its path as `<NAME>_FILE`.
+The deployed `docker-compose.yml` passes credentials as plain environment
+variables, so this module is inert there. It exists so a stack can supply them as
+Docker secrets instead without any code change; see `ROADMAP.md` 2.12.
+
+Call `load()` in every entrypoint before any configuration is read.
+
+Note for readers: this module is `local.secrets`. Python 3 resolves `import
+secrets` elsewhere in the package to the standard library, not to this file.
+"""
+import os
+
+# The settings a stack may supply as secret files. Any other `*_FILE` variable is
+# resolved the same way; this list documents the contract and is what the release
+# gate checks against.
+SECRET_FILE_SETTINGS = (
+    'DATABASE_URL',
+    'DATABASE_ADMIN_URL',
+    'DATABASE_PASSWORD',
+    'DATABASE_ADMIN_PASSWORD',
+    'APP_DB_PASSWORD',
+    'AWS_ACCESS_KEY_ID',
+    'AWS_SECRET_ACCESS_KEY',
+    'OPERATOR_PASSWORD',
+    'PAYMENT_TOKEN',
+    'PAYMENT_WEBHOOK_SECRET',
+    'TINY_TOKEN',
+    'WHATSAPP_TOKEN',
+)
+
+SUFFIX = '_FILE'
+
+
+def read_secret(path):
+    """One secret's value, without the newline an editor or `docker secret` adds.
+
+    Only a single trailing newline is removed: everything else is part of the
+    value, because a generated password may legitimately end in whitespace.
+    """
+    with open(path, 'r', encoding='utf-8') as handle:
+        value = handle.read()
+    if value.endswith('\r\n'):
+        return value[:-2]
+    if value.endswith('\n'):
+        return value[:-1]
+    return value
+
+
+def load(environ=None):
+    """Replace every `<NAME>_FILE` path with `<NAME>` holding the file's contents.
+
+    Fails closed. An unreadable secret, an empty one, or a name supplied both
+    directly and as a file is a configuration error, and starting anyway would
+    mean running with a credential nobody intended. Never logs a value.
+    """
+    environ = os.environ if environ is None else environ
+    resolved = []
+    for key in sorted(k for k in environ if k.endswith(SUFFIX) and len(k) > len(SUFFIX)):
+        name = key[:-len(SUFFIX)]
+        path = environ[key].strip()
+        if not path:
+            raise RuntimeError(f'{key} is set but empty; point it at a secret file')
+        if environ.get(name):
+            raise RuntimeError(
+                f'{name} and {key} are both set; supply the value or the file, not both')
+        try:
+            value = read_secret(path)
+        except OSError as exc:
+            raise RuntimeError(f'{key} could not be read: {exc.strerror}') from None
+        if not value:
+            raise RuntimeError(f'{key} points at an empty secret file')
+        environ[name] = value
+        resolved.append(name)
+    return resolved