> ## Documentation Index
> Fetch the complete documentation index at: https://docs.docyard.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# Security model

# Docyard v2 - Design Discussion

*Last updated: March 2026*

***

## 1. REVISED: Configurable Security Model Per Artifact Type

### Core Decision

All security models are available and **configured by the distributor per artifact type**. When a distributor creates an artifact type template, they specify which access control model to use.

### Security Access Models

Distributors configure one of these models per artifact type template:

| Model        | Description                                            | Use Case                                          |
| ------------ | ------------------------------------------------------ | ------------------------------------------------- |
| `open`       | Any collector with matching keys can access            | Public documents, standard insurance declarations |
| `declared`   | Only collectors who declared the lock types during KYC | Semi-private documents where legitimacy matters   |
| `invited`    | Only collectors invited by the distributor             | Partner relationships, B2B integrations           |
| `restricted` | Requires admin + distributor approval per collector    | Highly sensitive documents (PHI, classified)      |

### Configuration Example

```json theme={null}
POST /templates
{
  "name": "Insurance Declaration Page",
  "description": "Standard insurance policy declaration",
  "access_model": "declared",
  "locks": [
    {
      "name": "policy_number",
      "data_type": "string",
      "weight": 20,
      "required": true
    },
    {
      "name": "mortgagee_name",
      "data_type": "string", 
      "weight": 5,
      "required": false
    }
  ],
  "required_declared_locks": ["policy_number"],
  "threshold": 20
}
```

### How Each Model Works

#### Model: `open`

**Behavior:**

* Any collector can sign up (KYC optional)
* Any collector can search and retrieve
* No lock type declarations required
* Standard rate limiting applies

**Use for:**

* Public records
* Standard insurance declarations
* Documents intended for broad distribution

**Example:**

```json theme={null}
{
  "access_model": "open",
  "locks": [
    {"name": "policy_number", "weight": 25}
  ],
  "threshold": 25
}
```

#### Model: `declared`

**Behavior:**

* Collector must complete KYC
* Collector must declare which lock types they have access to
* System validates: collector can ONLY use declared lock types
* Access denied if collector tries undeclared locks

**Configuration Options:**

```json theme={null}
{
  "access_model": "declared",
  "required_declared_locks": ["policy_number", "loan_number"],
  "optional_declared_locks": ["mortgagee_name"],
  "allow_partial_match": true
}
```

**Use for:**

* Most insurance documents
* Mortgage documents
* Any document where legitimacy matters

**Security Logic:**

```
1. Collector declares: "I have policy_numbers from carriers A, B, C"
2. Collector presents: policy_number = "POL-12345678"
3. System checks: Is "policy_number" in collector's declared locks?
4. If YES: Calculate score and check threshold
5. If NO: Access denied - "You must declare this lock type in your KYC"
```

#### Model: `invited`

**Behavior:**

* Distributor generates invite codes/links
* Only collectors with valid invites can access
* Invites can be scoped (specific artifact types or all artifacts)
* Invites can expire

**Invite Flow:**

```
1. Distributor generates invite: "Bank of America needs access"
2. Distributor sends invite link to Bank of America
3. Bank of America signs up WITH the invite code
4. Bank of America gets access to invited artifact types
5. Access is logged and attributed to the invite
```

**Configuration:**

```json theme={null}
{
  "access_model": "invited",
  "invite_scope": "all_artifacts", // or "this_type_only"
  "invite_expires_days": 30
}
```

**Use for:**

* Known business partners
* Contractual relationships
* When distributor wants control over who accesses

#### Model: `restricted`

**Behavior:**

* Combines `declared` + `invited` + admin approval
* Collector must complete KYC with declarations
* Collector must have invite from distributor
* Admin must approve the collector-distributor relationship
* Highest security tier

**Approval Flow:**

```
1. Collector declares lock types in KYC
2. Distributor invites collector
3. System flags: "Restricted access request pending"
4. Admin reviews:
   - Verify collector's declarations
   - Verify business relationship exists
   - Check compliance requirements
5. Admin approves → Access granted
6. Admin rejects → Access denied
```

**Use for:**

* Healthcare documents (PHI)
* Classified documents
* Documents requiring regulatory compliance

### Collector Onboarding Flow by Model

```mermaid theme={null}
flowchart TD
    C[Collector Signs Up]
    
    C --> KYC{Complete KYC?}
    KYC -->|Required for declared/restricted| KD[KYC with Lock Declaration]
    KYC -->|Optional for open| KO[Basic Account]
    
    KD --> INV{Has Invite?}
    INV -->|Yes| INV_OK[Link to Distributor]
    INV -->|No| NO_INV[Access to OPEN artifacts only]
    
    INV_OK --> AD{Access Model?}
    AD -->|declared| D_OK[Access OK]
    AD -->|invited| I_OK[Access OK]
    AD -->|restricted| RES_CHECK{Admin Approved?}
    
    RES_CHECK -->|Yes| RES_OK[Access OK]
    RES_CHECK -->|No| RES_WAIT[Pending Approval]
    
    KO --> ACCESS[Can access OPEN artifacts]
    D_OK --> ACCESS2[Can access DECLARED artifacts]
    I_OK --> ACCESS3[Can access INVITED artifacts]
    RES_OK --> ACCESS4[Can access RESTRICTED artifacts]
```

***

## 2. Design Gaps & Mitigations (Updated for Configurable Model)

### 2.1 The Brute Force Problem → SOLVED by `declared` model

**Attack:** Automated guessing of lock values

**Solution:**

* Use `declared` or `restricted` model
* Collector must declare the lock type in KYC
* Even if they guess the value, they can't use it without declaring it first
* KYC verification prevents false declarations

**Rate Limiting Still Applies:**

* Per-collector rate limits regardless of model
* Anomaly detection for unusual access patterns
* CAPTCHA after N failed attempts

***

### 2.2 The Social Engineering Problem → MITIGATED by KYC verification

**Attack:** False declarations during KYC

**Solutions by Model:**

| Model        | Protection                                      |
| ------------ | ----------------------------------------------- |
| `open`       | No declarations needed - accept risk            |
| `declared`   | Require documentation proof for sensitive locks |
| `invited`    | Invite implies existing relationship            |
| `restricted` | Admin approval required                         |

**For `declared` model, we can require:**

* Proof documentation (carrier agreements, contracts)
* Reference checks with known distributors
* Period re-verification
* Spot-checks by admins

***

### 2.3 The Data Leak Problem → ACCEPTED as distributor responsibility

**Attack:** Collector downloads and misuses data

**Mitigations:**

* Watermarking retrieved documents (tracked by model)
* Full audit logging (who, what, when)
* Rate limiting on retrieval volume
* Legal agreements in ToS

**Responsibility:**

* **Open model**: Distributor assumes full risk
* **Declared model**: Distributor + Docyard shared (verification of declarations)
* **Invited/Restricted**: Higher confidence in collector legitimacy

***

### 2.4 The Insider Threat Problem → COLLECTOR RESPONSIBILITY

**Attack:** Employee abuse or credential theft

**Mitigations:**

* Audit logging for all retrievals (distributor can review)
* API key rotation recommendations
* Require collector to implement their own access controls

**NOT Dockyard's responsibility** - we authenticate the organization, not individual employees.

***

### 2.5 The Template Pollution Problem → ADMIN VETTING

**Attack:** Malicious or confusing templates

**Solution:**

* All templates require admin approval (already in design)
* Template name/description review
* Reject templates designed for phishing/social engineering
* `restricted` model requires extra vetting

***

### 2.6 The Lock Collision Problem → NAMESPACING

**Attack:** Same lock name, different meanings

**Solution:**

* Namespace locks in `declared`/`restricted` models: `acme:policy_number`
* Format validation patterns per distributor
* Document type matching for retrieval

**Trade-off**: Namespacing breaks "universal search" but provides security. Use `open` model for universal search scenarios.

***

### 2.7 The Threshold Manipulation Problem → ENFORCE MINIMUMS

**Attack:** Distributor sets threshold too low

**Solution:**

* Minimum threshold enforced by access model:
  * `open`: Minimum threshold = 5
  * `declared`: Minimum threshold = 10
  * `invited`: Minimum threshold = 10
  * `restricted`: Minimum threshold = 15
* Admin can override/reject suspicious configurations
* Recommended threshold ranges per lock type

***

### 2.8 The Orphan Artifact Problem → SUNSET CLAUSE

**Attack:** Distributor disappears, artifacts remain accessible

**Solution:**

* Auto-revocation after 180 days of distributor inactivity
* Artifacts flagged as "orphaned" after 90 days
* Distributor receives warnings at 60, 90, 180 days
* Admin can extend or transfer ownership

***

### 2.9 The Regulatory Compliance Problem → MODEL-BASED

**Attack:** Documents contain regulated data

**Solution:**

* Use `restricted` model for regulated content
* Mandatory data classification
* Compliance mode for healthcare/finance
* Enhanced audit trails for restricted artifacts

**Responsibility Matrix:**

| Content Type       | Required Model | Who's Responsible             |
| ------------------ | -------------- | ----------------------------- |
| Public records     | `open`         | Distributor                   |
| Standard insurance | `declared`     | Distributor + Docyard (KYC)   |
| Mortgage docs      | `declared`     | Distributor + Docyard (KYC)   |
| Healthcare (PHI)   | `restricted`   | Distributor + Docyard + Admin |
| Classified         | `restricted`   | Distributor + Admin           |

***

### 2.10 The Geographic Jurisdiction Problem → DATA RESIDENCY

**Attack:** Multi-jurisdiction compliance issues

**Solution:**

* Configure data residency per artifact type:

```json theme={null}
{
  "access_model": "restricted",
  "data_residency": "US", // EU, UK, etc.
  "compliance_requirements": ["HIPAA", "GDPR"]
}
```

* Region-specific encryption keys
* Legal hold capabilities for restricted model

***

## 3. REVISED: Artifact Type Template Schema

```json theme={null}
{
  "template_id": "uuid",
  "name": "Insurance Declaration Page",
  "description": "Standard insurance policy declaration",
  
  "access_control": {
    "model": "declared",
    "required_declared_locks": ["policy_number"],
    "optional_declared_locks": ["mortgagee_name"],
    "allow_partial_match": true,
    "minimum_threshold": 10
  },
  
  "locks": [
    {
      "name": "policy_number",
      "data_type": "string",
      "description": "Insurance policy identifier",
      "validation": { "pattern": "^POL-[0-9]{8}$" },
      "weight": 20,
      "required": true
    }
  ],
  
  "default_threshold": 20,
  
  "compliance": {
    "data_residency": "US",
    "retention_days": 2555,
    "requires_legal_hold": false
  },
  
  "status": "published",
  "created_at": "2026-03-15T10:00:00Z"
}
```

***

## 4. REVISED: MVP Security Model

For initial release, support ALL models but with different KYC requirements:

| Model        | MVP Support | KYC Required     | Admin Vetting          |
| ------------ | ----------- | ---------------- | ---------------------- |
| `open`       | ✅ Yes       | Optional         | Template only          |
| `declared`   | ✅ Yes       | Required         | Template + KYC         |
| `invited`    | ✅ Yes       | Required         | Template + KYC         |
| `restricted` | ✅ Yes       | Required + Proof | Template + KYC + Admin |

### MVP Implementation Priority:

**Phase 1 (Launch):**

* `open` model - immediate deployment
* `declared` model - with basic KYC

**Phase 2 (Month 2):**

* `invited` model
* Enhanced KYC with documentation

**Phase 3 (Month 3):**

* `restricted` model
* Admin approval workflow

***

## 5. REVISED: Discussion Points

**Point 1:** Configurability gives distributors control but adds complexity. Do we provide clear guidance on which model to choose?

**Point 2:** The `declared` model is likely to be most popular. Do we make it the default for new templates?

**Point 3:** Model mixing: Should a collector with `declared` access to Carrier A's documents also access Carrier B's `declared` documents? Or is it scoped by invite/relationship?

**Point 4:** Admin overhead: `restricted` model requires manual admin approval. What's our SLA for approvals?

**Point 5:** Lock type verification in `declared` model: Do we require proof for ALL declarations or just sensitive ones (SSN, DOB)?

***

## 6. Implementation Checklist

* [ ] Add `access_control` object to template schema
* [ ] Implement collector lock declaration during KYC
* [ ] Build invite system infrastructure
* [ ] Create admin approval workflow for `restricted` model
* [ ] Add data residency configuration
* [ ] Implement auto-revocation for inactive distributors
* [ ] Build audit logging for all models
* [ ] Create distributor guidance on model selection
* [ ] Add rate limiting per model tier
* [ ] Build anomaly detection for `open` model

***

*This document reflects the configurable security model per artifact type. Updated based on decision to allow all options.*