From 20c9ba35a667e938731f437ef94c5049df98b753 Mon Sep 17 00:00:00 2001 From: Amirhossein Khalili Date: Thu, 20 Aug 2026 18:18:45 +0330 Subject: [PATCH] docs(api): set analytics audit retention --- docs/API-SPEC.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/API-SPEC.md b/docs/API-SPEC.md index 791d64a..b01ec09 100644 --- a/docs/API-SPEC.md +++ b/docs/API-SPEC.md @@ -238,7 +238,7 @@ Limits are enforced before enqueuing or expensive work where possible. User and Record login success/failure category, logout, analytics start/deduplication, manual retry, SSE authorization/replay reset, detail access, and CSV export requested/completed/rejected/aborted. Export audit records include user id, merchant id, canonical view/filter fingerprint, period id, row count, byte count, result, request id, and timestamps—not exported row values, payer tokens, credentials, raw cursors, filenames from users, or peer data. -Minimal demo authentication audit retention remains 30 days. Retention for analytics-access/export audit records is unresolved and must be approved before implementation. +Minimal demo authentication audit retention remains 30 days. Analytics-access and CSV-export audit records are retained for 90 days, are accessible only to explicitly authorized backend operators, and are automatically deleted after the retention window. The MVP has no merchant-facing audit endpoint or audit-history UI. ### Metrics and traces @@ -261,6 +261,7 @@ Correlate `requestId`, authenticated user/merchant internal ids, run id, section - Request/rate/export limits reject before expensive work and return Problem Details plus `Retry-After` where applicable. - Problem responses keep HTTP status and `status` aligned, expose stable `code`, and leak no stack, SQL, secret, cursor content, peer identity, or cross-tenant existence. - Contract/security tests cover schema examples, unknown fields/params, cross-tenant ids and cursors, stale event ids, idempotency races, export filter parity, formula injection, row/byte/deadline caps, and sensitive-field absence. +- Analytics-access and CSV-export audit records are visible only to authorized backend operators and are deleted after 90 days. ## Boundaries @@ -274,13 +275,13 @@ Correlate `requestId`, authenticated user/merchant internal ids, run id, section - CSV export is capped at 100,000 rows, 50 MiB estimated uncompressed output, and a 60-second deadline. - CSV export is limited to 3 requests per 10 minutes with burst 1 in independent authenticated-user and merchant buckets. - CSV uses UTF-8 with a BOM, Persian column names separated by normal spaces, and Persian status labels. Numeric cells remain plain calculation-safe numbers and timestamps remain UTC ISO values. +- Analytics-access and CSV-export audit records are retained for 90 days and are accessible only to explicitly authorized backend operators; the MVP exposes no merchant audit-history surface. ## Remaining product questions -1. Define retention and operator access policy for analytics-access and CSV-export audit records; Identity's 30-day demo-auth retention does not automatically cover these events. -2. Confirm whether terminal identifiers may be shown/exported as their existing opaque source reference or require a separate merchant-facing display alias. -3. Choose the production base URI used for dereferenceable Problem Details `type` documentation; `https://api.zarinpal.example/problems/...` is a non-production placeholder in the draft contract. -4. Approve or revise the proposed public-edge request limits: 16 KiB for JSON bodies and 8 KiB for the request target/query string. +1. Confirm whether terminal identifiers may be shown/exported as their existing opaque source reference or require a separate merchant-facing display alias. +2. Choose the production base URI used for dereferenceable Problem Details `type` documentation; `https://api.zarinpal.example/problems/...` is a non-production placeholder in the draft contract. +3. Approve or revise the proposed public-edge request limits: 16 KiB for JSON bodies and 8 KiB for the request target/query string. ## Standards references