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

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:

{
  "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:

{
  "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:

Collector declares: "I have policy_numbers from carriers A, B, C"
Collector presents: policy_number = "POL-12345678"
System checks: Is "policy_number" in collector's declared locks?
If YES: Calculate score and check threshold
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:

Distributor generates invite: "Bank of America needs access"
Distributor sends invite link to Bank of America
Bank of America signs up WITH the invite code
Bank of America gets access to invited artifact types
Access is logged and attributed to the invite

Configuration:

{
  "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

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

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:

{
  "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

{
  "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

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

Get Started

Core Concepts

Guides

Industry Examples

API Reference

Artifact Types

Ramps (Distributor)

Docks (Collector)

Artifacts

Audit

Design Discussion

Admin

Security model

Docyard v2 - Design Discussion

1. REVISED: Configurable Security Model Per Artifact Type

Core Decision

Security Access Models

Configuration Example

How Each Model Works

Model: `open`

Model: `declared`

Model: `invited`

Model: `restricted`

Collector Onboarding Flow by Model

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

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

2.3 The Data Leak Problem → ACCEPTED as distributor responsibility

2.4 The Insider Threat Problem → COLLECTOR RESPONSIBILITY

2.5 The Template Pollution Problem → ADMIN VETTING

2.6 The Lock Collision Problem → NAMESPACING

2.7 The Threshold Manipulation Problem → ENFORCE MINIMUMS

2.8 The Orphan Artifact Problem → SUNSET CLAUSE

2.9 The Regulatory Compliance Problem → MODEL-BASED

2.10 The Geographic Jurisdiction Problem → DATA RESIDENCY

3. REVISED: Artifact Type Template Schema

4. REVISED: MVP Security Model

MVP Implementation Priority:

5. REVISED: Discussion Points

6. Implementation Checklist

Get Started

Core Concepts

Guides

Industry Examples

API Reference

Artifact Types

Ramps (Distributor)

Docks (Collector)

Artifacts

Audit

Design Discussion

Admin

​Docyard v2 - Design Discussion

​1. REVISED: Configurable Security Model Per Artifact Type

​Core Decision

​Security Access Models

​Configuration Example

​How Each Model Works

​Model: open

​Model: declared

​Model: invited

​Model: restricted

​Collector Onboarding Flow by Model

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

​2.1 The Brute Force Problem → SOLVED by declared model

​2.2 The Social Engineering Problem → MITIGATED by KYC verification

​2.3 The Data Leak Problem → ACCEPTED as distributor responsibility

​2.4 The Insider Threat Problem → COLLECTOR RESPONSIBILITY

​2.5 The Template Pollution Problem → ADMIN VETTING

​2.6 The Lock Collision Problem → NAMESPACING

​2.7 The Threshold Manipulation Problem → ENFORCE MINIMUMS

​2.8 The Orphan Artifact Problem → SUNSET CLAUSE

​2.9 The Regulatory Compliance Problem → MODEL-BASED

​2.10 The Geographic Jurisdiction Problem → DATA RESIDENCY

​3. REVISED: Artifact Type Template Schema

​4. REVISED: MVP Security Model

​MVP Implementation Priority:

​5. REVISED: Discussion Points

​6. Implementation Checklist

Docyard v2 - Design Discussion

1. REVISED: Configurable Security Model Per Artifact Type

Core Decision

Security Access Models

Configuration Example

How Each Model Works

Model: `open`

Model: `declared`

Model: `invited`

Model: `restricted`

Collector Onboarding Flow by Model

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

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

2.2 The Social Engineering Problem → MITIGATED by KYC verification

2.3 The Data Leak Problem → ACCEPTED as distributor responsibility

2.4 The Insider Threat Problem → COLLECTOR RESPONSIBILITY

2.5 The Template Pollution Problem → ADMIN VETTING

2.6 The Lock Collision Problem → NAMESPACING

2.7 The Threshold Manipulation Problem → ENFORCE MINIMUMS

2.8 The Orphan Artifact Problem → SUNSET CLAUSE

2.9 The Regulatory Compliance Problem → MODEL-BASED

2.10 The Geographic Jurisdiction Problem → DATA RESIDENCY

3. REVISED: Artifact Type Template Schema

4. REVISED: MVP Security Model

MVP Implementation Priority:

5. REVISED: Discussion Points

6. Implementation Checklist