+257

Packages/ATProto/Sources/ATProto/OAuth/Scope.swift

reviewed

··· 1 1 + import Foundation 2 2 + 3 3 + /// atproto OAuth scope, per https://atproto.com/specs/permission. 4 4 + /// 5 5 + /// pdfs only uses three resource types. `.rpc`, `.identity`, `.account` 6 6 + /// exist in the spec but aren't needed for the filesystem-over-PDS use 7 7 + /// case, so they're not modeled here. Parsing unknown resource types 8 8 + /// returns nil. 9 9 + public enum Scope: Hashable, Sendable, Codable { 10 10 + case atproto 11 11 + case repo(collections: Set<Collection>, actions: Set<Action>?) 12 12 + case blob(accepts: Set<String>) 13 13 + 14 14 + public enum Collection: Hashable, Sendable { 15 15 + case wildcard 16 16 + case nsid(String) 17 17 + 18 18 + var rawValue: String { 19 19 + switch self { 20 20 + case .wildcard: return "*" 21 21 + case .nsid(let s): return s 22 22 + } 23 23 + } 24 24 + 25 25 + static func parse(_ s: String) -> Collection? { 26 26 + if s == "*" { return .wildcard } 27 27 + guard !s.isEmpty else { return nil } 28 28 + return .nsid(s) 29 29 + } 30 30 + } 31 31 + 32 32 + public enum Action: String, Hashable, Sendable, CaseIterable { 33 33 + case create, update, delete 34 34 + } 35 35 + 36 36 + /// Convenience factory for a collection-scoped repo permission with 37 37 + /// default actions (create+update+delete). 38 38 + public static func repo(collection: String) -> Scope { 39 39 + .repo(collections: [.nsid(collection)], actions: nil) 40 40 + } 41 41 + 42 42 + // MARK: - Scope-string parsing 43 43 + 44 44 + /// Parses a single scope string per the atproto permission grammar. 45 45 + /// Returns nil for unrecognized resource types or malformed input. 46 46 + public init?(_ rawValue: String) { 47 47 + guard !rawValue.isEmpty else { return nil } 48 48 + // Split resource / positional / query. 49 49 + let (resource, positional, query) = Self.split(rawValue) 50 50 + guard let resource else { return nil } 51 51 + 52 52 + switch resource { 53 53 + case "atproto": 54 54 + guard positional == nil, query.isEmpty else { return nil } 55 55 + self = .atproto 56 56 + 57 57 + case "repo": 58 58 + // Collection: positional OR `?collection=...` array. Not both. 59 59 + var collections: Set<Collection> = [] 60 60 + if let pos = positional { 61 61 + if query["collection"] != nil { return nil } // both forms forbidden 62 62 + guard let c = Collection.parse(pos) else { return nil } 63 63 + collections = [c] 64 64 + } 65 65 + if let queryCollections = query["collection"] { 66 66 + for qc in queryCollections { 67 67 + guard let c = Collection.parse(qc) else { return nil } 68 68 + collections.insert(c) 69 69 + } 70 70 + } 71 71 + guard !collections.isEmpty else { return nil } 72 72 + 73 73 + // Actions: optional array. nil = all three default. 74 74 + let actions: Set<Action>? 75 75 + if let queryActions = query["action"] { 76 76 + var parsed: Set<Action> = [] 77 77 + for qa in queryActions { 78 78 + guard let a = Action(rawValue: qa) else { return nil } 79 79 + parsed.insert(a) 80 80 + } 81 81 + actions = parsed.isEmpty ? nil : parsed 82 82 + } else { 83 83 + actions = nil 84 84 + } 85 85 + self = .repo(collections: collections, actions: actions) 86 86 + 87 87 + case "blob": 88 88 + // MIME: positional single OR `?accept=...` array. Not both. 89 89 + var accepts: Set<String> = [] 90 90 + if let pos = positional { 91 91 + if query["accept"] != nil { return nil } 92 92 + accepts = [pos] 93 93 + } 94 94 + if let qa = query["accept"] { 95 95 + for m in qa { accepts.insert(m) } 96 96 + } 97 97 + guard !accepts.isEmpty else { return nil } 98 98 + self = .blob(accepts: accepts) 99 99 + 100 100 + default: 101 101 + return nil 102 102 + } 103 103 + } 104 104 + 105 105 + // MARK: - Scope-string formatting 106 106 + 107 107 + public var rawValue: String { 108 108 + switch self { 109 109 + case .atproto: 110 110 + return "atproto" 111 111 + case .repo(let collections, let actions): 112 112 + let sortedCollections = collections.map(\.rawValue).sorted() 113 113 + var s: String 114 114 + if sortedCollections.count == 1 { 115 115 + s = "repo:\(sortedCollections[0])" 116 116 + } else { 117 117 + let joined = sortedCollections.map { "collection=\($0)" }.joined(separator: "&") 118 118 + s = "repo?\(joined)" 119 119 + } 120 120 + if let actions, !actions.isEmpty { 121 121 + let sortedActions = actions.map(\.rawValue).sorted() 122 122 + let joined = sortedActions.map { "action=\($0)" }.joined(separator: "&") 123 123 + s += (s.contains("?") ? "&" : "?") + joined 124 124 + } 125 125 + return s 126 126 + case .blob(let accepts): 127 127 + let sorted = accepts.sorted() 128 128 + if sorted.count == 1 { 129 129 + return "blob:\(sorted[0])" 130 130 + } 131 131 + let joined = sorted.map { "accept=\($0)" }.joined(separator: "&") 132 132 + return "blob?\(joined)" 133 133 + } 134 134 + } 135 135 + 136 136 + // MARK: - Set helpers 137 137 + 138 138 + /// Space-separated scope string form (alphabetically sorted). 139 139 + public static func formatted(_ scopes: Set<Scope>) -> String { 140 140 + scopes.map(\.rawValue).sorted().joined(separator: " ") 141 141 + } 142 142 + 143 143 + /// Parses a space-separated scope string. Unknown tokens are ignored. 144 144 + public static func parse(_ s: String) -> Set<Scope> { 145 145 + Set(s.split(whereSeparator: \.isWhitespace).compactMap { Scope(String($0)) }) 146 146 + } 147 147 + 148 148 + // MARK: - Containment 149 149 + 150 150 + /// Does `granted` semantically cover every requested scope? 151 151 + /// Wildcard collections satisfy specific collections; granted action 152 152 + /// supersets (including nil = all three) satisfy narrower requests; 153 153 + /// blob `*/*` satisfies any specific MIME pattern; blob `image/*` 154 154 + /// satisfies `image/png` but not `video/mp4`. 155 155 + public static func satisfies(granted: Set<Scope>, requested: Set<Scope>) -> Bool { 156 156 + requested.allSatisfy { r in 157 157 + granted.contains { g in g.satisfies(r) } 158 158 + } 159 159 + } 160 160 + 161 161 + /// True iff `self` is at least as broad as `other` in the same resource 162 162 + /// family. Across resource families, always false. 163 163 + func satisfies(_ other: Scope) -> Bool { 164 164 + switch (self, other) { 165 165 + case (.atproto, .atproto): 166 166 + return true 167 167 + case let (.repo(gCols, gActions), .repo(rCols, rActions)): 168 168 + // Every requested collection must be covered by granted collections. 169 169 + let collectionsCover = rCols.allSatisfy { rc in 170 170 + gCols.contains(.wildcard) || gCols.contains(rc) 171 171 + } 172 172 + // Granted actions nil = all three, which covers anything. Else 173 173 + // granted must be a superset of requested (nil requested = all three). 174 174 + let grantedActions = gActions ?? Set(Action.allCases) 175 175 + let requestedActions = rActions ?? Set(Action.allCases) 176 176 + let actionsCover = requestedActions.isSubset(of: grantedActions) 177 177 + return collectionsCover && actionsCover 178 178 + case let (.blob(gAccepts), .blob(rAccepts)): 179 179 + return rAccepts.allSatisfy { r in 180 180 + gAccepts.contains { g in Self.mimeSatisfies(granted: g, requested: r) } 181 181 + } 182 182 + default: 183 183 + return false 184 184 + } 185 185 + } 186 186 + 187 187 + /// `*/*` satisfies anything. `image/*` satisfies `image/png`. Exact-exact. 188 188 + /// Prefix-only patterns like `*/html` are not valid per spec and not handled. 189 189 + static func mimeSatisfies(granted: String, requested: String) -> Bool { 190 190 + if granted == "*/*" { return true } 191 191 + if granted == requested { return true } 192 192 + // Wildcard on subtype: "image/*" 193 193 + let gParts = granted.split(separator: "/", maxSplits: 1).map(String.init) 194 194 + let rParts = requested.split(separator: "/", maxSplits: 1).map(String.init) 195 195 + guard gParts.count == 2, rParts.count == 2 else { return false } 196 196 + if gParts[1] == "*" && gParts[0] == rParts[0] { return true } 197 197 + return false 198 198 + } 199 199 + 200 200 + // MARK: - Codable (round-trips via the scope string form) 201 201 + 202 202 + public init(from decoder: Decoder) throws { 203 203 + let container = try decoder.singleValueContainer() 204 204 + let raw = try container.decode(String.self) 205 205 + guard let scope = Scope(raw) else { 206 206 + throw DecodingError.dataCorruptedError( 207 207 + in: container, debugDescription: "invalid scope string: \(raw)" 208 208 + ) 209 209 + } 210 210 + self = scope 211 211 + } 212 212 + 213 213 + public func encode(to encoder: Encoder) throws { 214 214 + var container = encoder.singleValueContainer() 215 215 + try container.encode(rawValue) 216 216 + } 217 217 + 218 218 + // MARK: - Raw string splitting 219 219 + 220 220 + /// Returns (resource, positional?, query[name: [values]]). 221 221 + /// Invalid inputs get resource=nil and the caller returns nil upstream. 222 222 + static func split(_ s: String) -> (resource: String?, positional: String?, query: [String: [String]]) { 223 223 + // Split "?" first. 224 224 + let qIdx = s.firstIndex(of: "?") 225 225 + let head = qIdx.map { String(s[..<$0]) } ?? s 226 226 + let queryString = qIdx.map { String(s[s.index(after: $0)...]) } ?? "" 227 227 + 228 228 + // Head: "resource" or "resource:positional" 229 229 + let headParts = head.split(separator: ":", maxSplits: 1).map(String.init) 230 230 + guard !headParts[0].isEmpty else { return (nil, nil, [:]) } 231 231 + let resource = headParts[0] 232 232 + let positional: String? = { 233 233 + if headParts.count == 2 { 234 234 + // Empty positional = malformed ("repo:" or "repo:?"). 235 235 + return headParts[1].isEmpty ? nil : headParts[1] 236 236 + } 237 237 + return nil 238 238 + }() 239 239 + // "repo:" with nothing after is malformed → treat resource as nil. 240 240 + if head.contains(":") && positional == nil { 241 241 + return (nil, nil, [:]) 242 242 + } 243 243 + 244 244 + // Query: &-separated name=value, percent-decoded. 245 245 + var query: [String: [String]] = [:] 246 246 + if !queryString.isEmpty { 247 247 + for pair in queryString.split(separator: "&") { 248 248 + let kv = pair.split(separator: "=", maxSplits: 1).map(String.init) 249 249 + guard kv.count == 2 else { continue } 250 250 + let name = kv[0].removingPercentEncoding ?? kv[0] 251 251 + let value = kv[1].removingPercentEncoding ?? kv[1] 252 252 + query[name, default: []].append(value) 253 253 + } 254 254 + } 255 255 + return (resource, positional, query) 256 256 + } 257 257 + }

+232

Packages/ATProto/Tests/ATProtoTests/OAuth/ScopeTests.swift

reviewed

··· 1 1 + import Foundation 2 2 + import Testing 3 3 + @testable import ATProto 4 4 + 5 5 + @Suite("Scope") 6 6 + struct ScopeTests { 7 7 + // MARK: - parse round-trips 8 8 + 9 9 + @Test("parses atproto") 10 10 + func parseAtproto() { 11 11 + #expect(Scope("atproto") == .atproto) 12 12 + } 13 13 + 14 14 + @Test("parses repo with positional collection, default actions = all three") 15 15 + func parseRepoPositional() { 16 16 + let scope = Scope("repo:app.bsky.feed.post") 17 17 + guard case let .repo(collections, actions) = scope else { 18 18 + Issue.record("expected .repo") 19 19 + return 20 20 + } 21 21 + #expect(collections == [.nsid("app.bsky.feed.post")]) 22 22 + #expect(actions == nil) // nil = all three default 23 23 + } 24 24 + 25 25 + @Test("parses repo with wildcard") 26 26 + func parseRepoWildcard() { 27 27 + let scope = Scope("repo:*") 28 28 + guard case let .repo(collections, _) = scope else { 29 29 + Issue.record("expected .repo") 30 30 + return 31 31 + } 32 32 + #expect(collections == [.wildcard]) 33 33 + } 34 34 + 35 35 + @Test("parses repo with actions query") 36 36 + func parseRepoActions() { 37 37 + let scope = Scope("repo:app.bsky.feed.post?action=create&action=update") 38 38 + guard case let .repo(_, actions) = scope else { 39 39 + Issue.record("expected .repo") 40 40 + return 41 41 + } 42 42 + #expect(actions == Set([Scope.Action.create, Scope.Action.update])) 43 43 + } 44 44 + 45 45 + @Test("parses repo with multiple collections as query params") 46 46 + func parseRepoMultipleCollections() { 47 47 + let scope = Scope("repo?collection=app.bsky.feed.post&collection=app.bsky.feed.like") 48 48 + guard case let .repo(collections, _) = scope else { 49 49 + Issue.record("expected .repo") 50 50 + return 51 51 + } 52 52 + #expect(collections == Set([ 53 53 + .nsid("app.bsky.feed.post"), 54 54 + .nsid("app.bsky.feed.like"), 55 55 + ])) 56 56 + } 57 57 + 58 58 + @Test("parses blob with positional MIME") 59 59 + func parseBlobPositional() { 60 60 + let scope = Scope("blob:*/*") 61 61 + guard case let .blob(accepts) = scope else { 62 62 + Issue.record("expected .blob") 63 63 + return 64 64 + } 65 65 + #expect(accepts == ["*/*"]) 66 66 + } 67 67 + 68 68 + @Test("parses blob with accept query") 69 69 + func parseBlobAcceptQuery() { 70 70 + let scope = Scope("blob?accept=image/*&accept=video/*") 71 71 + guard case let .blob(accepts) = scope else { 72 72 + Issue.record("expected .blob") 73 73 + return 74 74 + } 75 75 + #expect(accepts == ["image/*", "video/*"]) 76 76 + } 77 77 + 78 78 + @Test("rejects empty and unknown scope strings") 79 79 + func rejectUnknown() { 80 80 + #expect(Scope("") == nil) 81 81 + #expect(Scope("garbage") == nil) 82 82 + #expect(Scope("repo:") == nil) 83 83 + // Illegal: positional + same-name query arg 84 84 + #expect(Scope("repo:app.bsky.feed.post?collection=app.bsky.feed.like") == nil) 85 85 + } 86 86 + 87 87 + // MARK: - format round-trips 88 88 + 89 89 + @Test("atproto formats as \"atproto\"") 90 90 + func formatAtproto() { 91 91 + #expect(Scope.atproto.rawValue == "atproto") 92 92 + } 93 93 + 94 94 + @Test("repo formats with positional collection when possible") 95 95 + func formatRepoPositional() { 96 96 + let scope = Scope.repo(collections: [.nsid("app.bsky.feed.post")], actions: nil) 97 97 + #expect(scope.rawValue == "repo:app.bsky.feed.post") 98 98 + } 99 99 + 100 100 + @Test("repo formats with sorted action query when actions specified") 101 101 + func formatRepoWithActions() { 102 102 + let scope = Scope.repo( 103 103 + collections: [.nsid("app.bsky.feed.post")], 104 104 + actions: [.update, .create] 105 105 + ) 106 106 + #expect(scope.rawValue == "repo:app.bsky.feed.post?action=create&action=update") 107 107 + } 108 108 + 109 109 + @Test("repo formats multi-collection via query form (sorted)") 110 110 + func formatRepoMultiCollection() { 111 111 + let scope = Scope.repo( 112 112 + collections: [.nsid("app.bsky.feed.like"), .nsid("app.bsky.feed.post")], 113 113 + actions: nil 114 114 + ) 115 115 + #expect(scope.rawValue == "repo?collection=app.bsky.feed.like&collection=app.bsky.feed.post") 116 116 + } 117 117 + 118 118 + @Test("blob formats with positional when single accept") 119 119 + func formatBlobPositional() { 120 120 + #expect(Scope.blob(accepts: ["*/*"]).rawValue == "blob:*/*") 121 121 + } 122 122 + 123 123 + @Test("blob formats with query when multiple accepts") 124 124 + func formatBlobMulti() { 125 125 + let scope = Scope.blob(accepts: ["image/*", "video/*"]) 126 126 + #expect(scope.rawValue == "blob?accept=image/*&accept=video/*") 127 127 + } 128 128 + 129 129 + @Test("round-trip parse → format for representative scopes") 130 130 + func roundTrip() { 131 131 + let strings = [ 132 132 + "atproto", 133 133 + "repo:*", 134 134 + "repo:app.bsky.feed.post", 135 135 + "repo:app.bsky.feed.post?action=create&action=update", 136 136 + "repo?collection=app.bsky.feed.like&collection=app.bsky.feed.post", 137 137 + "blob:*/*", 138 138 + "blob?accept=image/*&accept=video/*", 139 139 + ] 140 140 + for s in strings { 141 141 + guard let parsed = Scope(s) else { 142 142 + Issue.record("failed to parse \(s)") 143 143 + continue 144 144 + } 145 145 + #expect(parsed.rawValue == s) 146 146 + } 147 147 + } 148 148 + 149 149 + // MARK: - Set serialization 150 150 + 151 151 + @Test("Set serializes space-separated, sorted") 152 152 + func setFormat() { 153 153 + let set: Set<Scope> = [ 154 154 + .atproto, 155 155 + .repo(collections: [.nsid("app.bsky.feed.post")], actions: nil), 156 156 + ] 157 157 + #expect(Scope.formatted(set) == "atproto repo:app.bsky.feed.post") 158 158 + } 159 159 + 160 160 + @Test("Set parses from space-separated, ignoring unknown tokens") 161 161 + func setParse() { 162 162 + let set = Scope.parse("atproto nonsense repo:app.bsky.feed.post blob:*/*") 163 163 + #expect(set.contains(.atproto)) 164 164 + #expect(set.contains(.repo(collections: [.nsid("app.bsky.feed.post")], actions: nil))) 165 165 + #expect(set.contains(.blob(accepts: ["*/*"]))) 166 166 + } 167 167 + 168 168 + // MARK: - Containment (used by ensureScope) 169 169 + 170 170 + @Test("granted atproto satisfies requested atproto") 171 171 + func containsAtproto() { 172 172 + let granted: Set<Scope> = [.atproto] 173 173 + let requested: Set<Scope> = [.atproto] 174 174 + #expect(Scope.satisfies(granted: granted, requested: requested)) 175 175 + } 176 176 + 177 177 + @Test("granted repo wildcard satisfies any specific repo request") 178 178 + func containsRepoWildcard() { 179 179 + let granted: Set<Scope> = [.repo(collections: [.wildcard], actions: nil)] 180 180 + let requested: Set<Scope> = [ 181 181 + .repo(collections: [.nsid("app.bsky.feed.post")], actions: [.create]), 182 182 + ] 183 183 + #expect(Scope.satisfies(granted: granted, requested: requested)) 184 184 + } 185 185 + 186 186 + @Test("granted collection + all-actions satisfies specific action on that collection") 187 187 + func containsActionSubset() { 188 188 + let granted: Set<Scope> = [ 189 189 + .repo(collections: [.nsid("app.bsky.feed.post")], actions: nil), 190 190 + ] 191 191 + let requested: Set<Scope> = [ 192 192 + .repo(collections: [.nsid("app.bsky.feed.post")], actions: [.create]), 193 193 + ] 194 194 + #expect(Scope.satisfies(granted: granted, requested: requested)) 195 195 + } 196 196 + 197 197 + @Test("granted collection does NOT satisfy a different collection request") 198 198 + func containsCollectionMismatch() { 199 199 + let granted: Set<Scope> = [ 200 200 + .repo(collections: [.nsid("app.bsky.feed.post")], actions: nil), 201 201 + ] 202 202 + let requested: Set<Scope> = [ 203 203 + .repo(collections: [.nsid("app.bsky.actor.profile")], actions: nil), 204 204 + ] 205 205 + #expect(!Scope.satisfies(granted: granted, requested: requested)) 206 206 + } 207 207 + 208 208 + @Test("granted action subset does NOT satisfy broader action request") 209 209 + func containsActionBroader() { 210 210 + let granted: Set<Scope> = [ 211 211 + .repo(collections: [.nsid("app.bsky.feed.post")], actions: [.create]), 212 212 + ] 213 213 + let requested: Set<Scope> = [ 214 214 + .repo(collections: [.nsid("app.bsky.feed.post")], actions: [.create, .delete]), 215 215 + ] 216 216 + #expect(!Scope.satisfies(granted: granted, requested: requested)) 217 217 + } 218 218 + 219 219 + @Test("granted blob */* satisfies any blob request") 220 220 + func containsBlobWildcard() { 221 221 + let granted: Set<Scope> = [.blob(accepts: ["*/*"])] 222 222 + let requested: Set<Scope> = [.blob(accepts: ["image/png"])] 223 223 + #expect(Scope.satisfies(granted: granted, requested: requested)) 224 224 + } 225 225 + 226 226 + @Test("granted blob image/* does NOT satisfy video blob request") 227 227 + func containsBlobMismatch() { 228 228 + let granted: Set<Scope> = [.blob(accepts: ["image/*"])] 229 229 + let requested: Set<Scope> = [.blob(accepts: ["video/mp4"])] 230 230 + #expect(!Scope.satisfies(granted: granted, requested: requested)) 231 231 + } 232 232 + }