Access Control

ZAYAZ Access Control & Audience Governance Model

Unified permissions system for documentation, engines, APIs, code samples, and Ask ZARA

Purpose. This document defines the role model, audience types, security classifications, visibility rules, and enforcement mechanisms that govern access across the entire ZAYAZ platform — including the documentation system, associated files, code examples, engine specifications, risk models, Excel sheets, and conversational interfaces (Ask ZARA).

Scope. This framework applies to:

• The ZAYAZ Documentation System (Docusaurus)
• The ZAYAZ Search & Ask APIs
• Associated code repositories, Excel models, technical assets
• External contributors & external auditors/verifiers
• Internal engineering, management, and operations
• All future “DocuFlare” permission-management layers

⸻

1. Audience Groups

ZAYAZ separates users into structured “audience groups.” Each MDX page, code sample, asset, and engine can specify which groups may access it.

1.1 Core Internal Audiences

Audience Key	Description	Typical Access
internal-admin	Master clearance over all docs/assets	Everything
internal-cto	Deep engine IP, secret formulas, risk models	Critical docs & Excel
internal-engineering-core	Core engine team (MICE, FIRM, COSE)	Specs, schemas, algorithms
internal-engineering-product	Product developers	API docs, workflows
internal-management	Strategy, governance	Architecture overview, KPIs
internal-marketing	Safe, public-facing content	Overviews, diagrams
internal-support	Customer support teams	Troubleshooting, flows

⸻

1.2 External Audiences

Audience Key	Description	Access Grants
external-auditor	ESG auditors, lifecycle auditors	Traceability, lineage, engine rationale
external-verifier	Compliance/LCA verification bodies	High-level engine logic, rulebooks
external-authority	Environmental authorities & regulators	Carbon passport, compliance paths
external-ngo	NGOs reviewing methodology	Method papers, not IP
external-academic	Academia & research	Theory + non-secret formulas
enterprise-client-admin	Admin for enterprise clients	Full product usage & reporting docs
enterprise-client-standard	Standard client users	Operational usage docs

⸻

1.3 External Programmers & Contractors

We add a dedicated set of roles for outsourced development:

Audience Key	Description
external-dev-core	Trusted external senior developers
external-dev-frontend	Contractors for UI work
external-dev-backend	Contractors for API/backend work
external-dev-limited	New or screened contractors

These groups are essential so contractors do not see:

• proprietary Excel files
• calibration coefficients
• risk-engine internals
• unpublished algorithms
• internal performance models

⸻

2. Security Levels

Each asset or page has a security level defining its sensitivity.

Level	Description	Typical Use	External Visibility
public	Safe for full public access	marketing docs, public APIs	Yes
internal	For staff only, low risk	onboarding, process guides	No
confidential	Business-sensitive	client-specific integrations	No
restricted	High-value technical IP; unauthorized access harms competitive advantage	ZARA, core engines, internal models	No
secret	Mission-critical platform internals	cryptographic systems, proprietary algorithms	No
critical	Catastrophic if exposed	keys, signing systems, identity exchanges	No

This lets you programmatically block Ask ZARA, search results, or indexers from loading or exposing high-level information.

⸻

3. Classification Tags

Classifications provide an additional semantic layer:

Tag.	Use Case.
IP-Core	Core algorithms
IP-Excel	Sensitive Excel-based models
Risk-Model	FIRM / Monte Carlo / Bayesian models
Compliance	Authority-facing docs
Client-Visible	Safe for external clients
Audit	Safe for auditors/verifiers
UI / API	Engineering-level technical structure
Legacy-Internal	Old content retained for reference

This allows smart filtering, search shaping, and Ask ZARA masking.

⸻

4. Frontmatter Specification

Standard MDX Access-Control Header

---
id: access-contol
title: ZAYAZ Access Control & Audience Governance Model
slug: /security/access-contol

hub: system-info
module: access-contol
source_file: /system-info/security/zayaz-access-control-governance.mdx

sidebar_label: Access Control & Audience Governance
sidebar_position: 1
doc_type: spec
status: review

legacy_manual_ref: N/A
version: 0.1
owners: [cto@viroway.com]
last_updated: 2025-12-05

# Access Control
audience:
  - internal-admin
  - internal-cto
  - internal-engineering-core

# Descriptive Tags
tags: [internal, security, governance]

# Security/classification used by policy engine
security_level: internal
classification: [Workflow]
---

For a highly sensitive file:

audience:
  - internal-cto
  - internal-engineering-core
allowed_users:
  - maria@zayaz.io
  - nils@zayaz.io
security_level: critical
classification: [IP-Excel, Risk-Model]

For a public-safe doc:

audience: [public]
security_level: public

⸻

5. Enforcement Layers

5.1 Docusaurus Build-Time Filtering

A plugin evaluates:

audience ∩ USER_GROUPS ≠ ∅
AND
security_level ≤ user_permitted_level

If false → page is excluded from the site entirely.

This avoids:

• accidental leaks
• front-end hiding tricks
• search indexing leaks

You will generate multiple doc sites:

• docs-public
• docs-clients
• docs-auditors
• docs-internal
• docs-engineering-core

Each is a different static build with different filtering.

Multi-site builds give us:

Build Variant	What it contains	Who it serves
docs-public	Only public docs	External world
docs-clients	Public + client-level docs	Enterprise & clients
docs-auditors	Client + audit-level docs	Third-party auditors/verifiers
docs-internal	Internal docs, no IP-core	General internal teams
docs-engineering-core	Full system specs & protected IP	CTO + core engineers

⸻

5.2 Ask ZARA Enforcement

ZARA’s retrieval and response pipeline must apply the same rules:

Step 1 — Filter retrieved chunks

Only include embeddings where:

chunk.audience ∩ user_roles ≠ ∅
&&
chunk.security_level <= user_clearance

Step 2 — Mask citations

Citations pointing to blocked pages must be removed or replaced with:

“This information is not available under your access level.”

Step 3 — Redact sensitive formulas

Critical Excel models will have a summary field in the index for ZARA; the file itself is never shown.

⸻

5.3 Associated Files & Excel Protection

Excel sheets go into:

protected-assets/
  critical/
  secret/
  confidential/

Each file includes metadata used by:

• search indexer
• Ask ZARA’s source citation system
• link generator

Access control applies equally to files and MDX pages.

⸻

6. External Developer Control

External dev roles must never see:

• risk engines
• Excel-based models
• system-internal correlation logic
• proprietary risk or margin algorithms
• unpublished technical plans
• internal models & QDF reasoning

Assign them one of:

external-dev-core
external-dev-backend
external-dev-frontend
external-dev-limited

Then tag MDX accordingly.

⸻

7. Central Permissions Hub

DocuFlare architecture:

7.1 Purpose

DocuFlare is a central cloud service that manages:

• user → roles mapping
• roles → permissions mapping
• request-time evaluation (API-level)
• signed tokens for frontend builds
• audit logs for what content was accessed

7.2 Responsibilities

• Issue a JWT containing audience groups
• Provide an endpoint for Ask ZARA to resolve user permissions
• Integrate with GitHub for external dev onboarding
• Support temporary role elevation (“developer elevated for 72h”)
• Manage restricted vault items (Excel files, formulas)

7.3 Proposed API

GET /docuflare/v1/permissions/{user}
GET /docuflare/v1/roles
POST /docuflare/v1/update-role

⸻

8. Implementation Checklist

In Documentation

• Add frontmatter to all MDX files
• Add metadata to Excel and associated files
• Install Docusaurus permission plugin
• Generate multiple targeted builds
• Add GitHubRepoButton and linked asset menus

In Search / Ask APIs

• Attach audience/security metadata to vector chunks
• Enforce filtering in retrieval
• Redact disallowed citations
• Block source-level file access

For External Programmers

• Assign temporary roles
• Validate builds do not expose restricted content
• Isolate assets in protected storage buckets

⸻

9. Appendix: Enumerated Lists (for Excel)

Drop these directly into columns.

9.1 Audience Groups (Complete List)

public
internal-admin
internal-cto
internal-engineering-core
internal-engineering-product
internal-management
internal-marketing
internal-support
external-auditor
external-verifier
external-authority
external-ngo
external-academic
enterprise-client-admin
enterprise-client-standard
external-dev-core
external-dev-backend
external-dev-frontend
external-dev-limited

9.2 Security Levels

public
internal
confidential
secret
critical

9.3 Classification Tags

IP-Core
IP-Excel
Risk-Model
Engine
Schema
Compliance
Client-Visible
Audit
Legacy-Internal
UI
API
Workflow

⸻