hyb-oa/.trellis/spec/hyb-oa/security-privacy.md

Security And Privacy

Never Store In Repo / Trellis / Chat

• Passwords, token, Secret, private keys, EncodingAESKey.
• Full personal accounts, full phone numbers, full email addresses where not required for local config.
• Raw invoice images, contract bodies, bank statement originals, payment credentials, sensitive quotes, cost details.
• Complete local paths to confidential company directories.
• Enterprise WeChat raw payloads, full sp_no, full template IDs, full userid, form values, attachments or comments.

Trellis-Specific Rules

• .trellis/workspace/ is local-only by default.
• .trellis/tasks/ may contain PRD and acceptance context, but only in redacted form.
• scripts/qa/check-trellis-governance.mjs must pass before commit.

Scenario: Business Attachment Governance

1. Scope / Trigger

• Trigger: adding or changing OA business attachments for reimbursement, purchase, payment, contract, project or company-document workflows.
• Applies when an attachment is stored by the OA and can later be previewed, downloaded, reviewed or archived.
• Do not introduce a generic file-center or free directory upload unless a Trellis task explicitly reopens that architecture.

2. Signatures

• DB fields on business attachment models: governance_status, sensitivity_level, attachment_type, reviewed_by, reviewed_at, review_note, archived_by, archived_at, archive_note, download_policy.
• Upload multipart fields may include: governanceStatus, sensitivityLevel, attachmentType, downloadPolicy.
• API response fields must use camelCase: governanceStatus, sensitivityLevel, attachmentType, downloadPolicy, reviewedBy, reviewedAt, reviewNote, archivedBy, archivedAt, archiveNote.
• Download APIs may accept reason; sensitive or reason-required attachments must reject downloads without a non-empty reason.

3. Contracts

• Default status is approved unless the business workflow has a stricter state such as pending_review.
• Default sensitivity is internal; payment receipts and similarly sensitive financial proof should use confidential.
• index_only means OA stores the index/metadata, not the original file.
• Frontend labels are informational only; backend permission and download reason checks remain authoritative.
• Audit logs for downloads must include actor, business target, attachment ID, attachment type, sensitivity level, governance status and sanitized reason when provided.

4. Validation & Error Matrix

• Unknown governance enum in upload -> normalize to the module default, do not persist arbitrary strings.
• Sensitive or reason_required attachment download without reason -> 400 VALID_001 with { reason: "required" }.
• Missing attachment or missing stored object -> 404.
• User lacks business read permission -> 403 PERM_001.
• Download reason longer than the server limit -> trim before writing audit metadata.

5. Good/Base/Bad Cases

• Good: a bank receipt upload returns confidential, receipt, reason_required; download first asks for用途 and writes an audit log.
• Base: a reimbursement supporting material upload defaults to internal, supporting_material, standard and remains downloadable by authorized participants.
• Bad: a page hides the download button but the backend route still streams the file without permission or reason checks.
• Bad: Enterprise WeChat messages or reports include original attachments instead of OA links and desensitized summaries.

6. Tests Required

• Prisma validate after schema or migration changes.
• Backend route tests for default governance fields, custom multipart fields when exposed, sensitive-download reason rejection and audit extra metadata.
• Frontend typecheck/build after API type changes.
• Focused UI verification for pages that add attachment governance labels or download-reason interactions.

7. Wrong vs Correct

Wrong

return reply.send(stream);

Correct

const reason = sanitizeDownloadReason(request.query?.reason);
if (requiresDownloadReason(attachment) && !reason) {
  throw buildValidationError({ reason: "required" });
}
await prisma.auditLog.create({ data: buildDownloadAudit({ attachment, reason }) });
return reply.send(stream);

Scenario: Company Documents And OA Collaboration

1. Scope / Trigger

• Trigger: mapping company electronic documents, policy files, operations guidance, employee collaboration tasks or external-review materials into OA.
• Applies to docs, specs, evidence, tasks, OA attachments, Enterprise WeChat messages, AI/Codex-assisted processing and storage decisions.

2. Contracts

• OA is the operations control layer, not the full original-document library.
• The controlled company document master keeps full originals, historical packages and high-sensitivity materials.
• OA may store indexes, business object links, status, responsibility, hash or checksum summaries, archive-location summaries, review results and audit evidence.
• Necessary business originals may enter OA only through scoped business attachment flows such as contract, reimbursement, purchase, payment, project or policy workflows.
• Employee collaboration, external review, generated reports, Enterprise WeChat messages and AI/Codex work use redacted copies, aliases or summaries.
• Do not build or describe a generic file center unless a Trellis task explicitly reopens that architecture and defines permissions, audit, storage, backup and retention rules.

3. Storage Decision Defaults

• Current V0 may keep authorized business attachments on the deployment server, but it must not become a shared drive or full document mirror.
• If storage is insufficient, prefer index-only records plus controlled offline retrieval before moving high-sensitivity originals online.
• Cloud object storage or controlled NAS/MinIO must be private, accessed by the OA service account, and governed by OA permissions and download audit.
• A home NAS can be cold archive, secondary backup or low-risk S3-compatible trial storage; it is not the default production attachment store unless VPN, private bucket, UPS, alerts and restore drills are in place.

4. Forbidden Content

• Full local paths to confidential directories.
• Passwords, token, Secret, private keys, source packages and complete configuration files.
• ID-card, bank-card, payroll, social-security, tax and full bank-statement originals in normal OA attachment areas.
• Customer original material, sensitive quotes, contract bodies or signed packages outside authorized business flows.