# macadmins/escrow-buddy architecture

> Architecture diagram of the GitHub repository macadmins/escrow-buddy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/macadmins/escrow-buddy
- Repository: https://github.com/macadmins/escrow-buddy

## Overview

##### Project type and purpose
- Escrow Buddy is an open-source macOS authorization plugin (written in Objective-C/Swift) plus packaging scripts and CI workflows. Its purpose is to generate and escrow FileVault personal recovery keys to an MDM server when a Mac lacks one.

##### File structure
Top-level:
- “Escrow Buddy/” – Xcode project for the authorization plugin.
– EBAuthPlugin.h/.m: plugin entry points.
– Bridging header to mix Obj-C and Swift.
– Mechanisms/EBMechanism.swift & Invoke.swift: the logic that runs during authorization.
– Utility/AuthDBSetup.sh & AuthDBTeardown.sh: shell helpers to manipulate the authorization database.
- scripts/ – packaging tooling.
– build_and_pkg.sh: builds the plugin and creates a .pkg installer.
– pkg/ – payload layout and postinstall script.
– uninstall.sh
- .github/workflows – continuous integration definitions for building on push and PR.
- images/, README.md, LICENSE, CHANGELOG.md

##### README for additional insights
- Describes the high-level flow: MDM deploys installer, then on next user login the plugin creates a new FileVault key via `fdesetup`, which is automatically escrowed by the MDM’s FDERecoveryKeyEscrow payload.
- Dependencies: macOS ≥10.14.4, MDM with FileVault key-escrow support.

##### Main components
a. Developer/CI environment
– Xcode + Swift/Obj-C compiler
– build_and_pkg.sh & GitHub Actions (build_main.yml/build_pr.yml)
– Output: Signed .pkg installer
b. MDM Server
– Hosts the FDERecoveryKeyEscrow profile
– Delivers the Escrow Buddy .pkg to enrolled Macs
c. macOS Client
– Installer .pkg deploys:
- Authorization Plugin bundle (com.netflix.Escrow-Buddy) installed under /Library/…
- Utility scripts (AuthDBSetup/Teardown)
– Authorization Services
- On user login or when triggered by “defaults write … GenerateNewKey” setting
- Plugin (EBAuthPlugin) dispatches Mechanism (EBMechanism, Invoke)
– fdesetup Command
- Generates new FileVault personal recovery key
– MDM escrow endpoint
- The system’s FDERecoveryKeyEscrow payload automatically sends the new key back to the MDM
d. Local Authorization Database
– The plugin uses AuthDBSetup/Teardown to insert its mechanism into the auth chain

##### Component relationships and data flow
1. CI triggers build_and_pkg.sh → compiles plugin & scripts → creates .pkg
2. MDM deploys the .pkg to macOS clients
3. Admin sets `GenerateNewKey` preference via MDM-run shell command
4. User logs in → Authorization Services invokes EBAuthPlugin → EBMechanism.swift runs
5. Mechanism runs fdesetup → OS generates recovery key
6. macOS automatically escrows the key to MDM via the installed FDERecoveryKeyEscrow profile
7. Optionally, AuthDBTeardown cleans up the auth configuration

##### Architectural patterns and principles
- Plugin Architecture: leverages macOS Authorization Services API
- Modular layering:
- Core logic (Swift/Obj-C plugin)
- Utility scripts (bash) for pre/post auth DB changes
- Packaging scripts decoupled from code
- CI pipelines in GitHub Actions
- Separation of concerns: build vs. runtime; client vs. MDM vs. CI

##### Final advice
– Label every component clearly (include actual file/identifier names where helpful).
– Annotate key technologies (Swift, Objective-C, Bash, GitHub Actions, macOS Authorization Services, fdesetup, MDM API).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer/CI Environment
    subgraph "Developer/CI Environment"
        direction TB
        GA["GitHub Actions\n(build_main.yml / build_pr.yml)"]:::dev
        Xcode["Xcode + Swift/Obj-C Compiler"]:::dev
        BuildScript["build_and_pkg.sh"]:::dev
        SignedPkg["Signed .pkg Installer"]:::pkg
        GA -->|triggers| BuildScript
        BuildScript -->|uses| Xcode
        BuildScript -->|outputs| SignedPkg
    end

    %% MDM Server
    subgraph "MDM Server"
        direction TB
        MDM["MDM Server\n(FDERecoveryKeyEscrow Profile)"]:::mdm
    end

    %% macOS Client
    subgraph "macOS Client"
        direction TB
        Installer[".pkg Delivery & Installation"]:::pkg
        AuthPlugin["Authorization Plugin Bundle\n(com.netflix.Escrow-Buddy)"]:::client
        Scripts["Utility Scripts\n(AuthDBSetup / AuthDBTeardown)"]:::client
        AuthDB[(Local Authorization Database)]:::db
        AuthService["Authorization Services"]:::client
        EBAuthPlugin["EBAuthPlugin"]:::client
        Mechanism["EBMechanism & Invoke"]:::client
        FDEsetup["fdesetup Command"]:::client
        EscrowEndpoint["MDM Escrow Endpoint"]:::client
        Cleanup["AuthDBTeardown"]:::client
        Installer -->|installs| AuthPlugin
        Installer -->|installs| Scripts
        Scripts -->|setup hook| AuthDB
        AuthDB -->|auth chain| AuthService
        AuthService -->|invokes| EBAuthPlugin
        EBAuthPlugin -->|dispatches| Mechanism
        Mechanism -->|runs| FDEsetup
        FDEsetup -->|generates key| EscrowEndpoint
        EscrowEndpoint -->|escrows key| MDM
        Scripts -->|optional cleanup| Cleanup
    end

    %% Deploy flow
    SignedPkg -->|deployed to client| MDM
    MDM -->|delivers installer| Installer

    %% Admin trigger
    Admin["Admin sets GenerateNewKey Pref"]:::client
    Admin -->|triggers| AuthService

    %% Click Events
    click GA "https://github.com/macadmins/escrow-buddy/blob/main/.github/workflows/build_main.yml"
    click GA "https://github.com/macadmins/escrow-buddy/blob/main/.github/workflows/build_pr.yml"
    click BuildScript "https://github.com/macadmins/escrow-buddy/blob/main/scripts/build_and_pkg.sh"
    click Scripts "https://github.com/macadmins/escrow-buddy/tree/main/scripts/pkg/"
    click Cleanup "https://github.com/macadmins/escrow-buddy/blob/main/scripts/uninstall.sh"
    click Installer "https://github.com/macadmins/escrow-buddy/tree/main/scripts/pkg/postinstall"
    click Xcode "https://github.com/macadmins/escrow-buddy/blob/main/Escrow Buddy/Escrow Buddy.xcodeproj"
    click EBAuthPlugin "https://github.com/macadmins/escrow-buddy/blob/main/Escrow Buddy/EBAuthPlugin.h"
    click EBAuthPlugin "https://github.com/macadmins/escrow-buddy/blob/main/Escrow Buddy/EBAuthPlugin.m"
    click Xcode "https://github.com/macadmins/escrow-buddy/blob/main/Escrow Buddy/Escrow Buddy-Bridging-Header.h"
    click Mechanism "https://github.com/macadmins/escrow-buddy/blob/main/Escrow Buddy/Mechanisms/EBMechanism.swift"
    click Mechanism "https://github.com/macadmins/escrow-buddy/blob/main/Escrow Buddy/Mechanisms/Invoke.swift"
    click Scripts "https://github.com/macadmins/escrow-buddy/blob/main/Escrow Buddy/Utility/AuthDBSetup.sh"
    click Cleanup "https://github.com/macadmins/escrow-buddy/blob/main/Escrow Buddy/Utility/AuthDBTeardown.sh"

    %% Styles
    classDef dev fill:#DAE8FC,stroke:#6C8EBF,color:#1A237E
    classDef pkg fill:#F4F4F4,stroke:#888888,color:#000000
    classDef mdm fill:#FFE6CC,stroke:#D79B00,color:#663C00
    classDef client fill:#D5E8D4,stroke:#82B366,color:#273E13
    classDef db fill:#FFF2CC,stroke:#D6B656,color:#665F00
```
