ATIdentityTools

0.2.0

Star
A set of Swift utilities for resolving and validating DIDs and handles in the AT Protocol.
api atproto atprotocol bluesky swift swift-package-manager
ATProtoKit/ATIdentityTools

What's New

v0.2.0

2026-08-11T02:00:23Z

Version 0.2.0 includes the following changes:

New Features

  • Added VerifiedIdentity for displaying the relationship between an AT Protocol handle and a decentralized identifier (DID).
  • Expanded the DID and DID Document support in DIDCore.
    • General DID syntax and custom DID methods can now be represented.
    • Added validation for absolute and relative DID references.
    • Added typed support for DID Document contexts, controllers, services, authentication relationships, and verification methods.

Changes:

  • Added the PrivacyInfo.xcprivacy file.
  • Added DIDCore as an ATIdentityTools dependency.
    • DIDCore has always been included in this package, but ATIdentityTools can now use its types and methods directly.
  • Updated DID resolution and caching to use DIDCore.DIDDocument instead of the DID Document model from ATCommonWeb.
  • Simplified DID caching.
    • Added CacheFreshness for identifying fresh, stale, and expired entries.
    • Stale entries are refreshed before being returned.
    • Expired entries are resolved again instead of being returned.
    • Updated the DIDCache methods to focus on storing, retrieving, and removing entries.
  • Added NetworkTransport and URLSessionNetworkTransport for DID resolution.
    • The did:plc and did:web resolvers now use the same network transport.
  • Improved handle resolution.
    • Handles are now normalized and validated before lookup.
    • DNS is checked before HTTP, followed by the configured backup nameservers.
    • Added HandleResolutionMethod and HandleResolutionFailure to preserve errors from each attempted resolution method.
  • Backup nameserver lookups now support IPv4 and IPv6 addresses.
  • Renamed the following HandleResolver methods:
    • resolveDNS(with:) is now resolveDNS(for:).
    • resolveHTTP(with:) is now resolveHTTP(for:).
    • resolveDNSBackup(with:) is now resolveDNSBackup(for:).
    • Renamed willForceRefresh to forceRefresh in the DID resolver methods.
  • Resolver timeouts now use seconds instead of milliseconds and default to 3 seconds.
  • Added public initializers to HandleResolverOptions and DIDResolverOptions.
    • Both structs now conform to Sendable.
  • Updated the resolver protocols, models, and errors to improve their Sendable conformance.
  • Removed existential any from DIDMethod.didMethods.
  • Added more documentation, as well as sample code, for:
    • DIDResolver
    • DIDDocumentResolverProtocol
    • HandleResolver
    • IdentityResolver
    • VerifiedIdentity
  • Added more unit tests for:
    • DID and handle resolution.
    • DID syntax and reference validation.
    • did:web URL conversions.
    • DID Document validation.
    • Caching.
    • Custom network transports.
    • Backup nameserver resolution.
    • Resolver timeouts and error handling.
    • Verified AT Protocol identities.

Bug Fixes

  • Fixed malformed DID validation and did:web URL conversion errors.
  • Fixed an issue where resolver timeout values could be interpreted as milliseconds even though the resolver options documented them as seconds.
  • Fixed an issue where in-memory DID cache TTL values were treated as milliseconds instead of seconds.
  • Fixed an issue where resolved backup nameserver IP addresses were not stored and reused correctly.
  • Fixed an issue where duplicate DNS TXT records containing the same DID could be rejected.
  • Fixed an issue where conflicting DNS TXT records were not reported correctly.
  • Fixed an issue where HTTP handle resolution did not validate the response status or complete response body.
  • Fixed an issue where errors from failed handle-resolution methods could be discarded.
  • Fixed an issue where a resolved DID Document could contain an identifier different from the requested DID.
  • Fixed DID resolution to report missing documents correctly when a PLC directory or did:web server returns a 404 response.

Once again, thank you for your support. Please give feedback, bug reports, and contributions if you have time. Consider starring this project if you find it helpful, and feel free to donate an amount that reflects the value it has brought to you. Your support helps ensure the continued development and improvement of this project. You can also speak to me on Bluesky (@cjrriley.ca) for any questions.

An icon for ATIdentityTools, which contains three stacks of rounded rectangles in an isometric top view. At the top stack, there's an icon of a card with lines on the right side to signify information. On the left side, the at symbol is in a thick weight, with a pointed arrow at the tip, is displayed. The three stacks are, from top to bottom, blue, then two shades of purple.

ATIdentityTools

Decentralized Identity (DID) and handle utilities for the AT Protocol, written in Swift.

GitHub Repo stars

Static Badge GitHub Sponsors

ATIdentityTools is a Swift library for resolving and validating identities in the AT Protocol. Given the importance of identities, this package is needed to handle them. It supports handle resolution, DID Document resolution, and bidirectional identity verification.

This Swift package handles the following parts of a user account:

  • The handle.
  • The Decentralized Identifier (DID).
  • The DID Document.
  • The AT Protocol signing key and Personal Data Server (PDS).

A child package named DIDCore has additional features specific to DIDs.

This is a lightweight package that shouldn't take much in your project, but its importance shouldn't be understated. This works best with the ATProtoKit family of Swift packages, but you can also use it alongside any ATProto packages unrelated to ATProtoKit.

This package relates to identity resolution and validation. This, and DIDCore, are based on the identity and did packages from the official atproto TypeScript repository, respectively.

Quick Example

import ATIdentityTools

do {
    var resolver = IdentityResolver(
        handleOptions: HandleResolverOptions(timeout: 3),
        didOptions: DIDResolverOptions(
            timeout: 3,
            didCache: MemoryCache()
        )
    )

    let identity = try await resolver.resolveVerifiedIdentity(
        handle: "atproto.com"
    )

    print("Handle: \(identity.handle)")
    print("DID: \(identity.did)")
    print("PDS: \(identity.pds.absoluteString)")
} catch {
    print(error)
}

Installation

You can use the Swift Package Manager to download and import the library into your project:

dependencies: [
    .package(url: "https://github.com/ATProtoKit/ATIdentityTools.git", from: "0.2.0")
]

Then under targets:

targets: [
    .target(
        // name: "[name of target]",
        dependencies: [
            .product(name: "ATIdentityTools", package: "atidentitytools"),
            .product(name: "DIDCore", package: "atidentitytools")
        ]
    )
]

Requirements

To use ATIdentityTools in your apps, your app should target the specific version numbers:

  • iOS and iPadOS 14 or later.
  • macOS 13 or later.
  • tvOS 14 or later.
  • visionOS 1 or later.
  • watchOS 9 or later.

For Linux, you need to use Swift 6.0 or later. On Linux, the minimum requirements include:

  • Amazon Linux 2
  • Debian 12
  • Fedora 39
  • Red Hat UBI 9
  • Ubuntu 20.04

You can also use this project for any programs you make using Swift and running on Docker.

Warning

As of right now, Windows support is theoretically possible, but not has not been tested to work. Contributions and feedback on making it fully compatible for Windows and Windows Server are welcomed. WebAssembly and Android are currently not supported, but will be in the future.

Submitting Contributions and Feedback

While this project will change significantly, feedback, issues, and contributions are highly welcomed and encouraged. If you'd like to contribute to this project, please be sure to read both the API Guidelines as well as the Contributor Guidelines before submitting a pull request. Any issues (such as bug reports or feedback) can be submitted in the Issues tab. Finally, if there are any security vulnerabilities, please read SECURITY.md for how to report it.

If you have any questions, you can ask me on Bluesky (@cjrriley.ca). And while you're at it, give me a follow! I'm also active on the Bluesky API Touchers Discord server.

License

This Swift package is using the Apache 2.0 License. Please view LICENSE.md for more details.

The following third-party Swift packages have been used to help run ATIdentityTools:

Description

  • Swift Tools 5.9.0
View More Packages from this Author

Dependencies

Last updated: Mon Sep 07 2026 13:30:52 GMT-0900 (Hawaii-Aleutian Daylight Time)