Lesson 05 of 06 · published

Who May Read, Who May Write

~13 min · authorization, policy, registry, least-privilege, soul-vault

Level 0Loose File

0 XP0/43 lessons0/12 achievements

0/100 XP to next level100 XP to go0% complete

Two Questions, Asked Separately

Every request that reaches a share has already been through authentication: Delta knows which Mac is asking, from proof it trusts (the tailnet's own record of who owns an address, or a ticket that Mac was issued; track 4 is about both). Authorization is the next question, and the share answers it, not the server. A request carries two names: the Mac Delta verified, and the app that says it is asking, in the X-Delta-App header. A share has three lists to hold them against: readers, writers and apps.

A Policy Is a Set of Macs, Described, Not Listed

readers and writers are both a Policy, and a policy never hard-codes machines. It accepts exactly five keys and refuses any other (a typo in a declaration fails that share's load instead of silently granting or denying):

Key	Means	Resolved from
`fleet: true`	every Mac in Delta's fleet	the registry's fleet groups, minus the household's Mac
`roles`	whichever Mac holds a role, such as `workbench` or `pippa`	the port ledger's role placement
`groups`	every Mac in a named registry group	the fleet registry
`members`	the Mac where a named app's engine runs	the port ledger's placement of that member
`labels`	specific Macs by fleet label	as written (rarely the right choice)

Policy.labels() turns the description into a set of Macs on every call, from the registry as it is now. That is invariant 8 at work, no machine name in code, and it has a practical payoff: when an app's engine moves to another Mac, or the Pippa role moves with a hardware change, every share that named the member or the role follows it without a single declaration being edited.

The Rule, in Two Lines

The root class decides with two short methods:

can_read(mac, app): the app is allowed, and the Mac is this Mac or is among the readers.
can_write(mac, app): the share is writable(), the app is allowed, and the Mac is this Mac or is among the writers.

Three details hide in those lines. First, the Mac a share lives on always passes the Mac test, so an app on the owner's own Mac reads through the same rules without being listed. Second, the app test applies even there: being on the right Mac does not let the wrong app in. Third, writable() comes first, so no writers list, however generous, makes a read-only share writable. When a check fails, the server raises a named refusal, <mac> may not read <share> for <app>, and /v1/shares lists a caller only the shares whose readers include it.

The Apps List, and What It Is Worth

The root class defaults apps to ["*"], any app, which is right for the home folder: delta cp and any family app may read it. But the loader gives an app's share a different default: when a declaration names no apps, it gets [<its own repository>]. An app's share is private to that app unless the declaration widens it.

Be honest about what this list buys. The architecture document is: X-Delta-App is what the calling process says it is, on a Mac whose local token it holds. The Mac is verified by Delta; the app name is a claim made by a process that is already trusted to be on that Mac. The apps list keeps well-behaved apps in their lanes and makes mistakes loud. It is not a wall between two programs running under the same account, and a writer that must tell two such apps apart needs more than a header.

Three Shares, Three Audiences: Soul Vault

Soul Vault's declaration shows the whole vocabulary in one file. The store lives on the Mac that holds the Pippa role, and it is served three times, to three different audiences:

store: readers {"fleet": true}, writers {"fleet": true}, apps ["cwkSoulVault"]. Every family Mac reads the vault and may ask the store to write a note, and only Soul Vault's own client may do either.
household: readers {"groups": ["household"]}, no writers, and options.vaults narrowing it to two vaults. The household's Mac is outside Delta's fleet, so fleet: true never includes it; the only way in for that Mac is a share whose declaration names its group. This one does, read-only, for exactly two vaults.
vault-reader: readers {"groups": ["vault_reader"]}, the same two vaults, read-only: for a group of machines that run no Delta of their own and ask this Mac's gateway directly.

The household and vault-reader shares are a second child, ScopedStoreShare, whose writable() returns False. So a write call aimed at either is refused by the root's rule before the child's code is asked anything, and the child's own call refuses again for good measure. Least privilege here is not a promise in a comment; it is three declarations and one boolean.

Code

The policy and the two checks (trimmed excerpt)·python

# delta/shares.py — Policy, can_read and can_write (trimmed excerpt)

class Policy:
    """Who may: fleet labels, ledger roles, fleet groups, or the Macs hosting members."""

    KEYS = {"labels", "roles", "groups", "members", "fleet"}

    def __init__(self, spec):
        spec = spec or {}
        if not isinstance(spec, dict) or set(spec) - self.KEYS:
            raise ValueError(f"policy keys must be among {sorted(self.KEYS)}: {spec!r}")
        ...

    def labels(self):
        found = set(self.spec["labels"])
        if self.fleet:  # every Mac in Delta's fleet group, read live
            found.update(config.fleet_labels())
        for role in self.spec["roles"]:
            found.add(family.role_fleet_label(role))
        for group in self.spec["groups"]:
            found.update(family.fleet_labels(group))
        for member in self.spec["members"]:
            label = config.member_label(member)
            if label:
                found.add(label)
        return found


class DataShare:
    def _app_allowed(self, app):
        return "*" in self.apps or (app or "") in self.apps

    def can_read(self, label, app):
        return self._app_allowed(app) and (label == config.this_label() or self.readers.allows(label))

    def can_write(self, label, app):
        return self.writable() and self._app_allowed(app) and (
            label == config.this_label() or self.writers.allows(label))

Runnable: a policy described by role, group and member, checked against a request matrix·python

# Who may: a policy over Macs, an app list, and the Mac a share lives on.
REGISTRY = {
    "groups": {"maintenance": ["workbench", "laptop", "service"], "household": ["family-room"]},
    "roles": {"workbench": "workbench", "pippa": "service"},
    "members": {"gallery-app": "service"},        # the Mac each app's engine runs on
}
NEVER = set(REGISTRY["groups"]["household"])      # "fleet" never includes the household's Mac
THIS_MAC = "workbench"


class Policy:
    KEYS = {"labels", "roles", "groups", "members", "fleet"}

    def __init__(self, spec=None):
        spec = spec or {}
        if set(spec) - self.KEYS:
            raise ValueError(f"policy keys must be among {sorted(self.KEYS)}: {spec!r}")
        self.spec = spec

    def labels(self):
        """Resolved on every call, so a registry change needs no restart."""
        found = set(self.spec.get("labels", []))
        if self.spec.get("fleet"):
            found |= {m for g in REGISTRY["groups"].values() for m in g} - NEVER
        found |= {REGISTRY["roles"][r] for r in self.spec.get("roles", []) if r in REGISTRY["roles"]}
        for g in self.spec.get("groups", []):
            found |= set(REGISTRY["groups"].get(g, []))
        found |= {REGISTRY["members"][m] for m in self.spec.get("members", []) if m in REGISTRY["members"]}
        return found


class Share:
    def __init__(self, sid, readers=None, writers=None, apps=None, writable=False):
        self.id, self.readers, self.writers = sid, Policy(readers), Policy(writers)
        self.apps, self._writable = apps or ["*"], writable

    def _app_ok(self, app):
        return "*" in self.apps or (app or "") in self.apps

    def can_read(self, mac, app):
        return self._app_ok(app) and (mac == THIS_MAC or mac in self.readers.labels())

    def can_write(self, mac, app):
        return self._writable and self._app_ok(app) and (mac == THIS_MAC or mac in self.writers.labels())


if __name__ == "__main__":
    home = Share("home", readers={"fleet": True}, writers={"fleet": True}, writable=True)
    gallery = Share("gallery-app/library", readers={"members": ["gallery-app"]}, apps=["gallery-app"])
    family = Share("vault/household", readers={"groups": ["household"]}, apps=["vault"])
    asks = [(home, "laptop", "cli", "read"), (home, "family-room", "cli", "read"),
            (gallery, "service", "gallery-app", "read"), (gallery, "service", "other-app", "read"),
            (gallery, "laptop", "gallery-app", "read"), (gallery, "service", "gallery-app", "write"),
            (family, "family-room", "vault", "read"), (family, "family-room", "vault", "write")]
    for share, mac, app, verb in asks:
        ok = share.can_read(mac, app) if verb == "read" else share.can_write(mac, app)
        print(f"{mac:12} as {app:12} {verb:5} {share.id:22} -> {'allowed' if ok else 'refused'}")

External links

Exercise

Run the runnable block and check every verdict against the two rules. Then move the gallery app: change REGISTRY["members"]["gallery-app"] to "laptop" and run it again without touching any share. Which verdicts flip, and why did no declaration need editing? Finally, add a share whose readers policy contains the key "roels" and observe where the mistake surfaces.

Hint

The members policy resolves on every call, so the laptop now passes and the service Mac fails for the gallery share. The misspelled key raises ValueError in Policy.__init__, at construction: in Delta that becomes the share's load failure, listed in health, instead of a share that silently admits nobody.