Repository files navigation

Access control can't always be static.Sometimes the mutability, nullability and access of variables depends on context.When dealing with these scenarios, we usually end up writing wrappers or duplicate the class for each different context. Well no more!

Protected is a Swift Package that allows you to specify the read and write rights for any type, depending on context by using Phantom types.Here's a taste of the syntax (we will explain everything in time):

structMyRights:RightsManifest{typealiasProtectedType=Booklettitle=Write(\.title)letauthor=Read(\.author)}func work(book:Protected<Book,MyRights>){    book.title // ✅ works    book.title="Don Quixote" // ✅ works    book.author // ✅ works    book.author="" // ❌ will not compile    book.isbn // ❌ will not compile}

This project is heavily inspired by@sellmair'spost on Phantom Read Rights.For those curious Protected relies on phantom types anddynamic member look up to provide an easy API for specifying read and write rights for any type in Swift.

You can install Sync viaSwift Package Manager by adding the following line to yourPackage.swift:

import PackageDescriptionletpackage=Package([...]dependencies:[.package(url:"https://github.com/nerdsupremacist/Protected.git", from:"1.0.0")])

So let's imagine that you run a Book publishing company. Your codebase works with information about books at different stages of publishing.Most of the code revolves entirely around the following class:

publicclassBook{publicvartitle:String?publicvarauthor:String?publicvarisbn:String?}

So what's wrong with this code? Well plenty of things:

1. Everything is nullable. Despite the fact that there's places in our code where we can be sure that they're not null anymore.
2. Everyting can be read publicly.
3. Everything is mutable, all of the time. And if anything is mutable, you can bet someone will mutate it, and probably in a part of code where you are not expecting it.

One way to address this would be to create a different version ofBook for every scenario:PlannedBook,PrePublishingBook,PostPublishingBook,PublishedBook, etc. But this leads to an unsustainable amount of code duplication and added complexity.These things might not look to bad when it comes to a simple class with three attributes, but as your classes get more complicated and we get more and more cases, keeping track of what can be read and mutated where becomes very difficult.

Enter our package Protected. When working with Protected, you write your model once, and we change how you access it.We are mainly working with two things:

1. RightsManifests: basically a type that specifies to what you have access to and how much.
2. Protected: a wrapper that will enforce at compile time that you only read and write what's allowed by the manifest.

So for our book example, we can consider that we want to safely handle the pre-publishing stage of a book.At this stage the author name is already set and should be changed.The title is also set, but is open to change. The ISBN should not be read at all. For this case we can write aRightsManifest

structPrePublishRights:RightsManifest{typealiasProtectedType=Book    // a) Declare that we can read and write the titlelettitle=Write(\.title!) // b) with the ! enforce that at this stage it's no longer optional    // c) Declare that we can only read the name of the authorletauthor=Read(\.author!)        // Do not include any declaration for the ISBN}

A RightsManifest is a type that includes variables pointing to either:

• Write: can be read be written to
• Read: can only be read

Each attribute you declare in the manifest can then be read in that context. So let's try to use it:

letbook=Protected(Book(), by:PrePublishRights())book.title // ✅ worksbook.title="Don Quixote" // ✅ worksbook.author // ✅ worksbook.author="" // ❌ will not compilebook.isbn // ❌ will not compile

If your object contains nested types, you can specify in your manifest, the manifest that corresponds to that value, and Protected will in that case return aProtected ValueFor example, let's say that your books point to an Author object where you quite insecurely store the password (I've seen worse security):

classAuthor{varname:String?varpassword:String?}classBook{vartitle:String?varauthor:Author?}

And let's say that you want to make sure that when someone grabs the author object from your book, that they can't see the password either.For that you can start by creating the manifests for both types. And when it comes to specifying the read right to the author, you can include that it should be protected by your other Manifest:

structAuthorBasicRights:RightsManifest{typealiasProtectedType=Authorletname=Read(\.name)}structBookBasicRights:RightsManifest{typealiasProtectedType=Booklettitle=Write(\.title)    // specify that for the author you want the result to be protected by AuthorBasicRightsletauthor=Read(\.author).protected(by:AuthorBasicRights())}

With this when you try to use it, you won't be able to access the password:

letbook=Protected(Book(), by:BookBasicRights())book.title // ✅ worksletauthor= book.author // returns a Protected<Author, AuthorBasicRights>?author?.name // ✅ worksauthor?.password // ❌ will not compile

AllProtected values are designed to be changed. If you use the same object at different stages, you would like to change the rights associated with that object at any given time.That's whyProtected comes with a couple of functions prefixed byunsafeX to signal that you really should know what it is that you're doing with the object here.

For example let's imagine that you're writing a piece of code that will create an ISBN for a book and move it to the post publishing stage. So you can imagine that your rights look as follows:

structPrePublishRights:RightsManifest{typealiasProtectedType=Booklettitle=Write(\.title!)letauthor=Read(\.author!)}structPostPublishRights:RightsManifest{typealiasProtectedType=Booklettitle=Read(\.title!)letauthor=Read(\.author!)letisbn=Read(\.isbn!)}

When you publish the book, you will efectively transition your object to be governed by the pre publish rights to the post publish rights. You can do this with the method:unsafeMutateAndChangeRights:

func publish(book:Protected<Book,PrePublishRights>)->Protected<Book,PostPublishRights>{return book.unsafeMutateAndChangeRights(to:PostPublishRights()){ bookin         // here you have complete unsafe access to the underlying `book` object, absolutely no limitations        book.isbn=generateISBN()}}

OtherunsafeX functions to deal with the underlying data when needed include:

• unsafeMutate: let's you mutate the underlying value however you like.
• unsafeChangeRights: let's you create a new version of the protected, governed by a new manifest.
• unsafeMapAndChangeRights: let's you map the value onto a new one, and wrap it in a new protected governed by a different manifest.
• unsafeBypassRights: just get the value no matter what the manifest says.

Read rights don't necessarily need to be a keypath. For Read Rights you have multiple options for dealing with them.For example you can provide a more elaborate getter logic:

structAuthorBasicRights:RightsManifest{typealiasProtectedType=Authorletname=Read(\.name)letpassword=Read{obfuscate($0.password)}}

You can also include a.map after anyRead to manipulate the value:

structAuthorBasicRights:RightsManifest{typealiasProtectedType=Authorletname=Read(\.name)letpassword=Read(\.password).map{obfuscate($0)}}

This is not a perfect protection for no one to be able to access things they shouldn't.Protected is not a security framework, it will not prevent people from accessing or mutating anything.It is intended as an easy way to make safe usage clear and simple depending on context.

1. A code can always access everything using theunsafeX methods provided.
2. You can (but really shouldn't) include more rights whithin the extension of a manifest. This allows you to include more rights than intended while still appearing to be safe. Do not do this! Protected cannot protect you from doing this.

Contributions are welcome and encouraged!

Protected is available under the MIT license. See the LICENSE file for more info.