# Station profile and verified representation target

State: **PLANNED target**, 2026-10-02. Authority: maintainer requested the station/profile entity and the full representation-claim process discussed in this session. Owning implementation phases: [P30–P33 plan](docs-planning-STATION_PROFILE_PLAN.md); canonical tasks: [ROADMAP](Roadmap.md#station-profile-and-representation). No new entity, endpoint, signature verifier or permission is implemented by this document. Preserve [catalog rules](docs-product-STATION_CATALOG.md), existing account/social/media/location/moderation policies and explicit iOS deferral.

## Entity vocabulary and ownership

**Station (posto)** already exists in Directory as a canonical establishment UUID, identifiers and reviewed location. Extend it through declared interfaces; do not create a second station identity, reuse an ANP survey row as a profile or cast a CNPJ to UUID. A profile can exist without a representative or prices.

- **OperatingEntityRevision:** Directory-owned effective link between the station, the full branch CNPJ and its source-backed operating entity. Include validity/source revision and unresolved/conflict state; distinguish operator succession from transfer of the physical property. Canonical operator changes require verification, not a profile manager edit.
- **StationProfile:** proposed `stationprofile` module aggregate, one per existing station UUID. Own versioned permitted business information and publication state, never regulatory identity, price facts or precise location. Public display distinguishes official, community and business-provided fields. Without an active applicable grant, it has no representation badge.
- **RepresentationClaim:** private station-specific request from an active account, bound to the operating-entity revision, claimed role, explicit permissions, policy version and challenge/declaration. Requester identity comes from the authenticated account, not a submitted account ID.
- **ClaimProof:** private immutable signed bytes/reference/hash and verification outcomes, issuer/source facts, authority evidence and applicable retention deadlines. Differentiate electronic signature, identity linkage, powers of representation and station-operation evidence. A user-supplied report is not a trusted verification result.
- **RepresentationDecision:** append-only restricted decision, reviewer authority, reason, policy/proof versions and grant scope. Corrections and appeals create new decisions/cases; no rewrite of the original decision.
- **RepresentationGrant:** capability bound to account, station, operating-entity revision, approved scopes and validity/revocation/version. It confers representation, not ownership of the establishment or an organization-wide tenant role.
- **ProfileRevision:** attributable revision of business-provided fields with minimal actor/decision references and moderation/publication state. Retention and data-rights handling are defined before schema implementation; append-only business correction is not an unlimited personal-data retention exception.

Account owns authentication/session/key proof and account lifecycle. Moderation owns restricted operator roles, cases/actions and appeals; it invokes profile commands through explicit application ports. Directory owns operator/location revisions. Evidence owns existing ephemeral photo rules; private signed-document processing needs a distinct capability/retention contract. Platform owns transactional jobs and redacted telemetry. No new service, broker or tenant database.

## B-BR-P01–P16

- **P01 — Stable identity:** Profile and claim reference a real Directory UUID and its verified current operating-entity revision. Every branch is scoped explicitly. A parent-company proof needs an authenticated branch relationship and authority covering that branch; matching CNPJ root, brand or franchise name alone is insufficient.
- **P02 — Representation semantics:** Use a localized badge such as `Representante da empresa verificado` or `Perfil administrado pela empresa`. It asserts reviewed representation only, not property title, laboratory quality, price correctness or ANP endorsement. No manager badge until a valid applicable grant exists.
- **P03 — Free access and proof:** Any active free account can request representation. Claim/proof/status/management commands require live account session and existing contributor-key request proof. Public CNPJ, public ANP certificate, phone/email access, selfie, location/photo and business card are supplementary evidence, not sufficient authority. Payment never changes approval, trust or permissions.
- **P04 — Bound declaration:** Generate a high-entropy server challenge and exact declaration binding station UUID, full operating CNPJ/revision, claim/account reference, requested scopes, purpose, policy and server issue/expiry times. Freeze entropy/TTL/attempt/input limits in P30-T01. One challenge has one successful proof binding; identical retry is idempotent, changed/reused/wrong-account or wrong-station proof fails. Reissue produces a new version and invalidates earlier unused challenges.
- **P05 — Cryptographic validation:** Verify exact signed document bytes, trusted issuer chain, allowed signature format/algorithm, certificate identity, validity/revocation and declared policy time. Extract and compare the signed content against the server declaration; a visible stamp/QR code or altered unsigned PDF addition never authorizes a grant. Unverifiable chain/time/revocation or provider outage stays pending/requires review, never approved. Do not invent a timestamp from PDF display text. Validation has no arbitrary-URL fetch or unbounded parser execution.
- **P06 — Powers separate from signature:** A valid signature proves signer/integrity under its validation policy, not ownership or every asserted power. Check current independently obtained CNPJ/QSA and authentic corporate authority documents; determine administrator/representative/delegation scope and required joint signatures. Name-only/partial masked identifier matches cannot resolve identity. An e-CNPJ holder, accountant or certificate custodian is not automatically entitled to manage the profile. The applicant's identity must be connected to the signed authorization or independently verified mandate.
- **P07 — Routes and review:** Accept company-certificate proof with authority checks, or personal ICP-Brasil/gov.br signature with independently verified representation. Managers need a mandate from a person with sufficient powers. Initial grants require an authorized human decision; automation performs checks/triage, not unattended access transfer. Exceptional manual documents require issuer-authenticity checks and independent confirmation, with equivalent authority criteria; weaker evidence cannot become approval just because another provider failed.
- **P08 — Restricted bytes and privacy:** Never accept private keys, certificate passwords, PFX/P12 bundles or credentials. Signed PDFs preserve original bytes for verification; image optimization/OCR must not rewrite signature proof. Before intake, freeze document categories, sizes, active-content/parser protection, retention, private access, deletion and restoration. All app-owned photos and scanned images retain the existing all-copy maximum 24 hours, including images embedded as proof; packaging a scan as PDF cannot evade that cap. A genuine signed authorization has its own minimal reviewed retention, not an invented unlimited archive. No CPF, private documents, account/provider identity, contributor GPS or access URLs in public DTOs/logs/jobs/fixtures.
- **P09 — Atomic decision and grant:** Restricted operator review uses versioned current claim/proof/operator/account status. Approval atomically records decision, narrowly scoped grant, consumed proof binding and required publication/notification intent. Concurrent approval, cancellation, duplicate claim and outdated reviewer snapshots cannot yield broader or duplicate authority. Denial grants nothing. Reviewer cannot approve their own claim or use representation as moderator authority.
- **P10 — Capability matrix:** Initial proposed roles are verified administrator and delegated manager, not immutable property owner. Allowed scopes are bounded business profile edits and official business replies using existing feedback rules. Only explicitly authorized administrators may propose scoped invitations/revocations. Account/session/provider changes, stale operator revision, suspended/revoked/expired grant or required reauthentication failure deny sensitive writes immediately. Final scope names and fresh-auth/additional-factor policy freeze before handlers, including measured availability/recovery, not client-side role flags.
- **P11 — Field and fact boundaries:** Managers may update reviewed business-provided services, hours and contact/marketing fields accepted by the frozen P30 field policy. They request canonical name/address/location/operator corrections through Directory review; they never overwrite ANP facts. Official business replies obey existing 280-scalar text/author/moderation rules. Price submissions reuse existing account/key/location/evidence/consensus rules and may be labeled business-provided without extra vote weight. Profile photos/gallery, sponsored ranking or new price authority are outside this feature.
- **P12 — Community independence:** Representation gives no power to hide/delete other users' comments, alter ratings/votes, read private contributors or audit photos, suppress criticism or certify prices. A business report enters the ordinary restricted moderation path. Author deletion/moderation/erasure continue to govern the author's own replies; official attribution must not reveal private representative identity.
- **P13 — Delegation, transfer and operator change:** Invitation is scoped, expires, requires recipient authenticated acceptance and cannot exceed the verified delegator's authority. Transfer of administration requires recipient-specific verified authority, fresh confirmations and operator review; no first-claim-wins or last-admin-click takeover. Directory operator succession invalidates old applicability immediately; uncertainty or credible reviewed conflict can suspend sensitive writes. Removing the last administrator leads to reviewed recovery, never broadened powers for a manager. Historical replies retain truthful at-time business attribution and a superseded-representation context where needed.
- **P14 — Dispute and revocation:** A competing claim/report alone neither transfers access nor automatically removes a representative. Restricted operators triage evidence and may suspend applicable scopes for substantiated risk, with reason, notice, review and appeal. No automatic ban from report count. Revocation/expiry/account suspension takes effect at authorization time even if cleanup/jobs/cache purge fail. Public badge freshness is bounded and purge/TTL tested; it never grants access. Closed cases stay closed; new facts open linked new cases.
- **P15 — Recovery, deletion and audit:** Record only justified proof metadata and bounded audit, with separate owner/reviewer access. Define erasure/export/revocation handling across claims, documents, grants, profile history, replies, replicas and backups before migrations. Deleting an account revokes its grants; it does not remove the station or erase other accounts' community facts. Restore reapplies deletion/revocation ledgers before reads/writes and purges expired proof/photos. No rollback can resurrect revoked authority or expired proof. Historical audit is privacy-reviewed, not a justification to retain all documents indefinitely.
- **P16 — Safe operations and compatibility:** Freeze additive wire states, input limits and reviewer interfaces before implementation; existing operator CLI remains the authority, no public admin route or in-app moderator role. Current Moderation target enum does not include station claims: introduce an explicit tested target/command extension, not arbitrary strings. All writes re-check server-side applicability and expected versions; cached/mobile business badges never authorize. Preserve old clients with cautious unknown-state fallback, offline reads, MIT notices, package `com.anpfuel` and native iOS deferral.

## Proposed claim and grant states

Claim target states: `DRAFT`, `AWAITING_PROOF`, `CHECKING`, `NEEDS_INFORMATION`, `IN_REVIEW`, `APPROVED`, `DENIED`, `CANCELLED`, `EXPIRED`. P30-T01 freezes transitions and transport values before behavior. Source/verifier failure remains a pending state with a safe reason, never `APPROVED`. Need-more-information does not extend an existing photo deadline. Approved/denied/cancelled/expired are terminal for that claim; appeal or renewed proof opens a linked new request. No grant is inferred from the claim state without its actual atomic grant record.

Grant target states: `ACTIVE`, `SUSPENDED`, `REVOKED`, `EXPIRED`, with query-time validity/account/operator checks. Suspension needs an audited operator decision; restoration needs a fresh decision/check, not clearing a flag blindly. Reverification creates a new proof/decision version. Expired/revoked scope cannot be restored by a job replay or old mobile command.

## BUC-P01–P10

- **P01 Read a station profile:** anonymous reader sees station identity, reviewed public business fields, independent source/time labels, prices/feedback via existing contracts, and a truthful representation badge or no badge. No private person/proof/grant detail.
- **P02 Open a claim and declaration:** active free account selects an existing station and role, gets a private request and one-use declaration. Full-CNPJ/operator binding, duplicate/rate-limit/idempotency and denied proof cases run before HTTP implementation.
- **P03 Submit and verify proof:** account uploads only allowed private immutable signed bytes and necessary mandate evidence; server checks bounds and performs independent signature/content/identity/authority checks. Reuse/modified PDF/certificate mismatch/provider outage preserve pending/denial truth.
- **P04 Review and approve/deny:** restricted independent operator evaluates authoritative source facts and powers, requests missing evidence or atomically decides narrow scopes. Version conflict/self-review/parallel grant/account revocation/operator succession fail safely.
- **P05 Manage profile and reply officially:** verified representative with current scope/fresh proof edits permitted business fields or replies under existing feedback rules. Canonical facts/community reputation/other users remain outside authority. Offline retry reevaluates current authority.
- **P06 Invite or transfer:** verified administrator with delegation powers names a recipient/scope; recipient accepts with account/key proof. Transfer requires recipient-bound proof and review; deny capability escalation, expired invite and operator mismatch.
- **P07 Contest, suspend, revoke and appeal:** requester/representative reports impersonation or decision error privately. Operator reviews rather than report count deciding outcome; updates capability immediately with audit. New evidence opens a linked new case; no competitor account receives access automatically.
- **P08 Reverify succession and recovery:** operator change, loss of administrator account or expiring proof triggers a reviewed new claim. Revoke stale applicability immediately; preserve station/community history and safe at-time reply attribution. Recovery cannot rely solely on mutable phone/email contact.
- **P09 Erase/export/restore:** owner rights cover claim/proof/private identity with bounded audit exceptions explicitly defined. Account deletion revokes grants before background cleanup; restore cannot revive documents, grants or personalized exports. Other representatives' documents never enter an owner's export.
- **P10 Operate and accept:** scoped staff process claims and urgent impersonation cases with actual capacity/response evidence; test load, outages, privacy/recovery and affected real-device flows on a pinned artifact. Automated checks do not replace staffing or real trust-provider proof.

## MVP and provider boundary

Initial approval is human-reviewed, backed by independent signature and authority checks. Allow export/sign/import of a generated declaration; do not assume the private app can integrate directly with gov.br signing APIs. Use maintained verification tooling or a contracted permitted adapter after dependency/license/security review, not a homegrown PKI engine or unapproved scraping of VALIDAR. An operator may validate exact bytes directly with official tools under a documented permitted process; the applicant cannot submit a fabricated report as proof of validation.

Triage and source checks may be automated. Manual and automatic validation must enforce identical declaration/authority requirements. External requests happen outside DB locks, bounded and traceable by IDs only. Provider errors produce indeterminate results and reviewed recovery, not trust downgrade shortcuts. Future automated approval is a separate policy/task requiring measured fraud and revocation evidence; it is not delivered by this plan.