> ## 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.

# Lock-Key-Weight Model

> How access control works in the lake

# Lock-Key-Weight Model

The lock-key-weight model is the heart of Docyard's access control. It's simple, flexible, and powerful.

## The Core Concept

Every artifact in the lake has:

1. **Locks**: Metadata fields that define access requirements
2. **Keys**: Values for those metadata fields
3. **Weights**: Scores assigned to each lock type
4. **Threshold**: Minimum combined score required for access

Collectors retrieve artifacts by presenting keys. The system calculates the score. If the score meets or exceeds the threshold, access is granted.

## How It Works

<details>
  <summary>👆 Click to expand: Lock-Key-Weight Access Control Flow</summary>

  ```mermaid theme={null}
  flowchart TD
      subgraph UPLOAD["DISTRIBUTOR UPLOADS"]
          A1[Select Template]
          A2[Provide Lock Values]
          A3[Assign Weights]
          A4[Set Threshold]
          A5[Upload to Lake]
          A1 --> A2 --> A3 --> A4 --> A5
      end

      subgraph LAKE["THE LAKE"]
          ARTIFACT[Artifact with Locks]
      end

      subgraph RETRIEVAL["COLLECTOR RETRIEVES"]
          B1[Search Lake]
          B2[Present Keys]
          B3[Calculate Score]
          B4{Score >= Threshold?}
          B5[✅ GRANTED]
          B6[❌ DENIED]
          B1 --> B2 --> B3 --> B4
          B4 -->|Yes| B5
          B4 -->|No| B6
      end

      A5 --> ARTIFACT
      ARTIFACT --> B1

      style UPLOAD fill:#e8f5e9,stroke:#2e7d32
      style LAKE fill:#e1f5fe,stroke:#01579b
      style RETRIEVAL fill:#fff3e0,stroke:#ef6c00
      style B5 fill:#c8e6c9,stroke:#2e7d32
      style B6 fill:#ffcdd2,stroke:#c62828
  ```
</details>

### Step 1: Distributor Uploads Artifact

When uploading, the distributor:

1. Selects an artifact type template
2. Provides values (keys) for each lock
3. Assigns weights to each lock type
4. Sets a threshold score

```json theme={null}
{
  "locks": {
    "policy_number": { "value": "POL-12345678", "weight": 20 },
    "effective_date": { "value": "2026-03-15", "weight": 10 },
    "mortgagee_name": { "value": "FirstCity Bank", "weight": 5 }
  },
  "threshold": 20
}
```

### Step 2: Collector Attempts Retrieval

When a collector wants the artifact, they:

1. Search for artifacts
2. Present their keys
3. System calculates total score

```json theme={null}
POST /api/v1/dock/retrieve/{artifact_id}
{
  "keys": {
    "policy_number": "POL-12345678"
  }
}
```

### Step 3: Access Decision

The system calculates:

| Presented Key                   | Weight | Match? |
| ------------------------------- | ------ | ------ |
| policy\_number: POL-12345678    | 20     | ✅ Yes  |
| effective\_date: (not provided) | 10     | ❌ No   |
| mortgagee\_name: (not provided) | 5      | ❌ No   |

**Total Score**: 20\
**Threshold**: 20\
**Decision**: ✅ Access Granted (20 ≥ 20)

## Score Calculation Examples

### Example 1: Full Match

Collector has the policy number:

| Key             | Weight | Provided? |
| --------------- | ------ | --------- |
| policy\_number  | 20     | ✅         |
| effective\_date | 10     | ❌         |
| mortgagee\_name | 5      | ❌         |

**Score**: 20\
**Threshold**: 20\
**Result**: ✅ Access Granted

### Example 2: Partial Match (Enough)

Collector has mortgagee name AND effective date:

| Key             | Weight | Provided? |
| --------------- | ------ | --------- |
| policy\_number  | 20     | ❌         |
| effective\_date | 10     | ✅         |
| mortgagee\_name | 5      | ✅         |

**Score**: 10 + 5 = 15\
**Threshold**: 20\
**Result**: ❌ Access Denied (15 \< 20)

### Example 3: Multiple Partial Matches

Collector has all three keys:

| Key             | Weight | Provided? |
| --------------- | ------ | --------- |
| policy\_number  | 20     | ✅         |
| effective\_date | 10     | ✅         |
| mortgagee\_name | 5      | ✅         |

**Score**: 20 + 10 + 5 = 35\
**Threshold**: 20\
**Result**: ✅ Access Granted (35 ≥ 20)

## Why Weights Matter

Weights allow fine-grained access control:

### High-Security Artifact

```json theme={null}
{
  "locks": {
    "policy_number": { "weight": 30 },
    "effective_date": { "weight": 20 }
  },
  "threshold": 50
}
```

* Requires combining multiple strong keys
* A single key isn't enough
* Higher security

### Low-Security Artifact

```json theme={null}
{
  "locks": {
    "policy_number": { "weight": 40 }
  },
  "threshold": 20
}
```

* Single key grants access
* Easier for collectors
* Lower security

## Lock Types

Each lock type has:

| Property       | Description        | Example              |
| -------------- | ------------------ | -------------------- |
| **Name**       | Unique identifier  | `policy_number`      |
| **Data Type**  | Value type         | string, number, date |
| **Validation** | Format rules       | regex pattern        |
| **Weight**     | Score contribution | 20                   |

### Common Lock Types

| Lock Type        | Data Type | Description          | Typical Weight |
| ---------------- | --------- | -------------------- | -------------- |
| `policy_number`  | string    | Insurance policy ID  | 15-25          |
| `loan_number`    | string    | Loan identifier      | 15-25          |
| `effective_date` | date      | Effective date       | 5-10           |
| `mortgagee_name` | string    | Lender name          | 5-10           |
| `document_type`  | string    | Category of document | 5-10           |
| `address`        | string    | Property address     | 5-10           |
| `insured_name`   | string    | Insured person       | 5-10           |

## System vs Custom Lock Types

### System Lock Types

Mandatory for all artifacts:

| Lock Type       | Description          | Required? |
| --------------- | -------------------- | --------- |
| `document_type` | Category of document | ✅ Yes     |

### Custom Lock Types

Defined by distributors in their artifact type templates:

```json theme={null}
{
  "name": "vin_number",
  "data_type": "string",
  "description": "Vehicle identification number",
  "validation": { "pattern": "^[A-HJ-NPR-Z0-9]{17}$" },
  "weight": 15,
  "required": true
}
```

## Matching Logic

### Exact Match

For string locks, values must match exactly:

```
Artifact lock: policy_number = "POL-12345678"
Collector key: policy_number = "POL-12345678"
Result: ✅ Match
```

```
Artifact lock: policy_number = "POL-12345678"
Collector key: policy_number = "POL-87654321"
Result: ❌ No Match
```

### Partial Match (Optional)

For string locks, you can enable partial matching:

```
Artifact lock: mortgagee_name = "FirstCity Bank"
Collector key: mortgagee_name = "FirstCity"
Result: ✅ Match (if partial matching enabled)
```

### Date Range (Optional)

For date locks, you can match ranges:

```
Artifact lock: effective_date = "2026-03-15"
Collector key: effective_date_after = "2026-03-01", effective_date_before = "2026-03-31"
Result: ✅ Match
```

## Access Denied Scenarios

### Score Too Low

```json theme={null}
{
  "keys": { "mortgagee_name": "FirstCity Bank" },
  "result": {
    "score": 5,
    "threshold": 20,
    "status": "denied",
    "message": "Score (5) is below threshold (20). Provide more keys."
  }
}
```

### Missing Required Keys

```json theme={null}
{
  "keys": {},
  "result": {
    "score": 0,
    "threshold": 20,
    "status": "denied",
    "message": "No matching keys provided."
  }
}
```

## Benefits of Lock-Key-Weight

1. **Flexible**: Combine any keys to meet threshold
2. **Fine-grained**: Weights allow security tuning
3. **Simple**: No complex permission matrices
4. **Open**: Any collector can attempt access
5. **Secure**: Only those with real keys succeed

***

## Next Steps

* Learn about [Distributors](/concepts/distributors)
* Learn about [Collectors](/concepts/collectors)
* See the [API Reference](/api-reference/docks)