Merge remote-tracking branch 'refs/remotes/origin/develop'

Author: MasterJ93

Sources/ATProtoKit/APIReference/ComAtprotoAPI/ComAtprotoRepoDescribeRepoMethod.swift

@@ -32,8 +32,14 @@ extension ATProtoKit {
         _ repositoryDID: String,
         pdsURL: String? = nil
     ) async throws -> ComAtprotoLexicon.Repository.DescribeRepositoryOutput {
-        // TODO: Change this back to "\(self.pdsURL)" once ATIdentityProtocol has been implemented.
-        guard let requestURL = URL(string: "https://bsky.social/xrpc/com.atproto.repo.describeRepo") else {
+        let host: String
+        if let pdsURL, !pdsURL.isEmpty {
+            host = pdsURL
+        } else {
+            host = await resolvePDSHost(for: repositoryDID)
+        }
+
+        guard let requestURL = URL(string: "\(host)/xrpc/com.atproto.repo.describeRepo") else {
             throw ATRequestPrepareError.invalidRequestURL
         }
 
@@ -66,4 +72,27 @@ extension ATProtoKit {
             throw error
         }
     }
+
+    /// Determines the base hostname for a repository-scoped request.
+    ///
+    /// Some `com.atproto.repo.*` methods are implemented by the Personal Data Server (PDS) that
+    /// hosts the target repository, which may differ from the instance's own PDS. This resolves
+    /// the PDS service endpoint from the target DID via ``ATBuiltInIdentityResolver``, falling back
+    /// to the instance's own ``pdsURL`` (the prior behaviour, served via entryway proxying) when
+    /// resolution isn't possible.
+    ///
+    /// Resolution is only attempted when `repository` is a DID; handles fall through to the
+    /// instance's own host to preserve existing behaviour. Callers that already know the PDS URL
+    /// should use it directly instead of calling this method.
+    ///
+    /// - Parameter repository: The decentralized identifier (DID) or handle of the target repository.
+    /// - Returns: The base hostname to use for the request.
+    func resolvePDSHost(for repository: String) async -> String {
+        if repository.hasPrefix("did:"),
+           let endpoint = try? await ATBuiltInIdentityResolver().resolvePDSEndpoint(from: repository) {
+            return endpoint
+        }
+
+        return pdsURL
+    }
 }

Sources/ATProtoKit/APIReference/ComAtprotoAPI/ComAtprotoRepoListRecordsMethod.swift

@@ -28,6 +28,7 @@ extension ATProtoKit {
     ///   - cursor: The mark used to indicate the starting point for the next set
     ///   of results. Optional.
     ///   - isArrayReverse: Indicates whether the list of records is listed in reverse. Optional.
+    ///   - pdsURL: The URL of the Personal Data Server (PDS). Optional. Defaults to `nil`.
     /// - Returns: An array of records, with an optional cursor to extend the array.
     ///
     /// - Throws: An ``ATProtoError``-conforming error type, depending on the issue. Go to
@@ -37,10 +38,17 @@ extension ATProtoKit {
         collection: String,
         limit: Int? = 50,
         cursor: String? = nil,
-        isArrayReverse: Bool? = nil
+        isArrayReverse: Bool? = nil,
+        pdsURL: String? = nil
     ) async throws -> ComAtprotoLexicon.Repository.ListRecordsOutput {
-        // TODO: Change this back to "\(self.pdsURL)" once ATIdentityProtocol has been implemented.
-        guard let requestURL = URL(string: "https://bsky.social/xrpc/com.atproto.repo.listRecords") else {
+        let host: String
+        if let pdsURL, !pdsURL.isEmpty {
+            host = pdsURL
+        } else {
+            host = await resolvePDSHost(for: repository)
+        }
+
+        guard let requestURL = URL(string: "\(host)/xrpc/com.atproto.repo.listRecords") else {
             throw ATRequestPrepareError.invalidRequestURL
         }
 

Sources/ATProtoKit/Errors/ATProtoError.swift

@@ -207,6 +207,22 @@ public enum ATDIDError: ATProtoError {
     case failedToValidateViaRegex
 }
 
+/// An error type related to resolving an identity with ``ATBuiltInIdentityResolver``.
+public enum ATIdentityResolverError: ATProtoError {
+
+    /// The DID uses a method that the built-in resolver does not support.
+    case unsupportedDIDMethod(String)
+
+    /// The DID could not be turned into a valid DID-document URL.
+    case invalidDID(String)
+
+    /// The DID document could not be retrieved.
+    case didDocumentUnavailable(did: String)
+
+    /// The DID document did not declare an AT Protocol PDS service.
+    case pdsServiceNotFound(did: String)
+}
+
 /// An error type related to issues with handles.
 public enum ATHandleError: ATProtoError {
 

Sources/ATProtoKit/Utilities/APIHostname.swift

@@ -24,4 +24,7 @@ public enum APIHostname {
 
     /// The hostname for the Ozone moderation API ("https://mod.bsky.app").
     public static let moderation: String = "https://mod.bsky.app"
+
+    /// The hostname for the PLC directory ("https://plc.directory").
+    public static let plcDirectory: String = "https://plc.directory"
 }

Sources/ATProtoKit/Utilities/ATBuiltInIdentityResolver.swift

@@ -0,0 +1,97 @@
+//
+//  ATBuiltInIdentityResolver.swift
+//  ATProtoKit
+//
+//  Created by Christopher Jr Riley on 2026-06-30.
+//
+
+import Foundation
+#if canImport(FoundationNetworking)
+import FoundationNetworking
+#endif
+
+/// A lightweight, dependency-free ``ATIdentityProtocol`` conformer.
+///
+/// This resolver maps a decentralized identifier (DID) to its Personal Data Server (PDS)
+/// service endpoint by fetching the DID document directly — without requiring ATIdentityTools
+/// or an authenticated session.
+///
+/// It supports the `did:plc` and `did:web` methods. For richer identity handling (such as
+/// handle verification or caching policies), conform a type to ``ATIdentityProtocol`` using a
+/// dedicated package like ATIdentityTools instead.
+public struct ATBuiltInIdentityResolver: ATIdentityProtocol {
+
+    /// The URL session used for the lookups.
+    public let urlSession: URLSession
+
+    /// The base hostname of the PLC directory.
+    public let plcDirectoryURL: String
+
+    /// Creates a new built-in identity resolver.
+    ///
+    /// - Parameters:
+    ///   - urlSession: The URL session used for the lookups. Defaults to `URLSession.shared`.
+    ///   - plcDirectoryURL: The base hostname of the PLC directory. Defaults to
+    ///   ``APIHostname/plcDirectory``.
+    public init(
+        urlSession: URLSession = .shared,
+        plcDirectoryURL: String = APIHostname.plcDirectory
+    ) {
+        self.urlSession = urlSession
+        self.plcDirectoryURL = plcDirectoryURL
+    }
+
+    public func resolvePDSEndpoint(from did: String) async throws -> String {
+        let documentURL = try didDocumentURL(for: did)
+
+        let (data, response) = try await urlSession.data(from: documentURL)
+        guard let httpResponse = response as? HTTPURLResponse,
+              (200..<300).contains(httpResponse.statusCode) else {
+            throw ATIdentityResolverError.didDocumentUnavailable(did: did)
+        }
+
+        let document = try JSONDecoder().decode(DIDDocument.self, from: data)
+
+        guard let service = try? document.checkServiceForATProto() else {
+            throw ATIdentityResolverError.pdsServiceNotFound(did: did)
+        }
+
+        return service.serviceEndpoint.absoluteString
+    }
+
+    /// Builds the DID-document URL for a supported DID method.
+    ///
+    /// - Parameter did: The DID to build the document URL for.
+    /// - Returns: The URL of the DID document.
+    private func didDocumentURL(for did: String) throws -> URL {
+        if did.hasPrefix("did:plc:") {
+            // did:plc:xxxx → https://plc.directory/did:plc:xxxx
+            guard let url = URL(string: "\(plcDirectoryURL)/\(did)") else {
+                throw ATIdentityResolverError.invalidDID(did)
+            }
+
+            return url
+        } else if did.hasPrefix("did:web:") {
+            // did:web:example.com     → https://example.com/.well-known/did.json
+            // did:web:example.com:a:b → https://example.com/a/b/did.json
+            let identifier = String(did.dropFirst("did:web:".count))
+            let segments = identifier.split(separator: ":").map(String.init)
+
+            guard let host = segments.first?.removingPercentEncoding else {
+                throw ATIdentityResolverError.invalidDID(did)
+            }
+
+            let path = segments.count > 1
+                ? "/" + segments.dropFirst().joined(separator: "/") + "/did.json"
+                : "/.well-known/did.json"
+
+            guard let url = URL(string: "https://\(host)\(path)") else {
+                throw ATIdentityResolverError.invalidDID(did)
+            }
+
+            return url
+        } else {
+            throw ATIdentityResolverError.unsupportedDIDMethod(did)
+        }
+    }
+}