Index of every page on this site: llms.txt
All skills
Run it yourself

Opinionated rules for production native iOS apps in Swift and SwiftUI, covering the Observation framework, Swift concurrency (async/await, actors, Sendable), URLSession networking against a JSON API, Keychain credential storage, StoreKit 2 purchases with server-side entitlements, testing, and App Store / TestFlight release workflows. Use when building or reviewing SwiftUI views, view models, networking, authentication, in-app purchases, concurrency code, or preparing an App Store submission.

Use this Skill: https://skilld.dev/gh/suleyman/fullstack-agent-skills/swift-ios

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

referencesnetworking-and-keychain.md

≈3.3k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Networking and Keychain

Reference implementations for the API client, JSON coding, token storage, and the session model. Adapt names. Keep the structure.

JSON coding that matches the API

The API sends camelCase keys, ISO 8601 UTC datetimes with fractional seconds, and string enums.

import Foundation

extension JSONDecoder {
    static let api: JSONDecoder = {
        let decoder = JSONDecoder()
        let withFraction = Date.ISO8601FormatStyle(includingFractionalSeconds: true)
        let withoutFraction = Date.ISO8601FormatStyle()
        decoder.dateDecodingStrategy = .custom { decoder in
            let value = try decoder.singleValueContainer().decode(String.self)
            if let date = try? withFraction.parse(value) { return date }
            if let date = try? withoutFraction.parse(value) { return date }
            throw DecodingError.dataCorrupted(.init(
                codingPath: decoder.codingPath,
                debugDescription: "Expected ISO 8601 date, got \(value)"
            ))
        }
        return decoder
    }()
}

extension JSONEncoder {
    static let api: JSONEncoder = {
        let encoder = JSONEncoder()
        encoder.dateEncodingStrategy = .iso8601
        return encoder
    }()
}

/// Server enums gain cases over time; old app versions must not fail to decode them.
enum OrderStatus: Decodable, Sendable, Equatable {
    case pending, paid, cancelled, unknown(String)

    init(from decoder: Decoder) throws {
        let raw = try decoder.singleValueContainer().decode(String.self)
        switch raw {
        case "pending": self = .pending
        case "paid": self = .paid
        case "cancelled": self = .cancelled
        default: self = .unknown(raw)
        }
    }
}

Cover the decoder with a fixture captured from the real API (2026-03-01T10:15:30.123456Z). Don't rely on a hand-typed example.

Errors

struct Problem: Decodable, Sendable {
    let code: String
    let title: String
    let status: Int
    let detail: String?
    let requestId: String?
}

enum APIError: Error, Sendable {
    case offline
    case transport(URLError)
    case sessionExpired
    case problem(Problem)
    case unexpectedStatus(Int, requestId: String?)
    case decoding(String)
}

extension Error {
    var isCancellation: Bool {
        self is CancellationError || (self as? URLError)?.code == .cancelled
    }
}

Endpoints

struct Endpoint<Response: Decodable & Sendable>: Sendable {
    var method = "GET"
    var path: String
    var query: [URLQueryItem] = []
    var body: Data?
}

extension Endpoint where Response == EventPage {
    static func upcomingEvents(cursor: String?) -> Self {
        var query = [URLQueryItem(name: "limit", value: "20")]
        if let cursor { query.append(URLQueryItem(name: "cursor", value: cursor)) }
        return Endpoint(path: "/v1/events", query: query)
    }
}

API client actor with single-flight refresh

protocol TokenProviding: Sendable {
    func accessToken() async -> String?
    /// Exchanges the refresh token for a new pair. Throws APIError.sessionExpired when the server rejects it.
    func refresh() async throws -> String
}

actor APIClient {
    private let baseURL: URL
    private let session: URLSession
    private let tokens: TokenProviding
    private var refreshTask: Task<String, Error>?

    init(baseURL: URL, tokens: TokenProviding) {
        let config = URLSessionConfiguration.default
        config.timeoutIntervalForRequest = 15
        config.httpAdditionalHeaders = ["Accept": "application/json"]
        self.baseURL = baseURL
        self.session = URLSession(configuration: config)
        self.tokens = tokens
    }

    func send<Response>(_ endpoint: Endpoint<Response>) async throws -> Response {
        let (data, response) = try await perform(endpoint, token: await tokens.accessToken())
        if response.statusCode == 401 {
            let fresh = try await refreshedToken()
            let (retryData, retryResponse) = try await perform(endpoint, token: fresh)
            return try decode(retryData, retryResponse)
        }
        return try decode(data, response)
    }

    /// Concurrent 401s share one refresh, because refresh tokens rotate and a second refresh would look like reuse.
    private func refreshedToken() async throws -> String {
        if let refreshTask { return try await refreshTask.value }
        let task = Task { try await tokens.refresh() }
        refreshTask = task
        defer { refreshTask = nil }
        return try await task.value
    }

    private func perform<Response>(_ endpoint: Endpoint<Response>, token: String?) async throws -> (Data, HTTPURLResponse) {
        var components = URLComponents(url: baseURL.appending(path: endpoint.path), resolvingAgainstBaseURL: false)!
        if !endpoint.query.isEmpty { components.queryItems = endpoint.query }

        var request = URLRequest(url: components.url!)
        request.httpMethod = endpoint.method
        request.httpBody = endpoint.body
        if endpoint.body != nil { request.setValue("application/json", forHTTPHeaderField: "Content-Type") }
        if let token { request.setValue("Bearer \(token)", forHTTPHeaderField: "Authorization") }

        do {
            let (data, response) = try await session.data(for: request)
            guard let http = response as? HTTPURLResponse else { throw APIError.unexpectedStatus(-1, requestId: nil) }
            return (data, http)
        } catch let error as URLError where error.code == .notConnectedToInternet {
            throw APIError.offline
        } catch let error as URLError where error.code != .cancelled {
            throw APIError.transport(error)
        }
    }

    private func decode<Response: Decodable>(_ data: Data, _ response: HTTPURLResponse) throws -> Response {
        let requestId = response.value(forHTTPHeaderField: "X-Request-ID")
        guard (200..<300).contains(response.statusCode) else {
            if response.statusCode == 401 { throw APIError.sessionExpired }
            if let problem = try? JSONDecoder.api.decode(Problem.self, from: data) { throw APIError.problem(problem) }
            throw APIError.unexpectedStatus(response.statusCode, requestId: requestId)
        }
        if Response.self == EmptyResponse.self, let empty = EmptyResponse() as? Response { return empty }
        do {
            return try JSONDecoder.api.decode(Response.self, from: data)
        } catch {
            throw APIError.decoding("\(error) [request \(requestId ?? "-")]")
        }
    }
}

struct EmptyResponse: Decodable, Sendable {}

The session layer handles APIError.sessionExpired by signing the user out (see below). Every other error goes to the screen's error state.

Keychain store

import Security

struct KeychainError: Error { let status: OSStatus }

struct KeychainStore: Sendable {
    let service: String

    func set(_ data: Data, for account: String) throws {
        let query: [String: Any] = [
            kSecClass as String: kSecClassGenericPassword,
            kSecAttrService as String: service,
            kSecAttrAccount as String: account,
        ]
        let attributes: [String: Any] = [
            kSecValueData as String: data,
            kSecAttrAccessible as String: kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly,
        ]
        let status = SecItemUpdate(query as CFDictionary, attributes as CFDictionary)
        if status == errSecItemNotFound {
            let addStatus = SecItemAdd(query.merging(attributes) { $1 } as CFDictionary, nil)
            guard addStatus == errSecSuccess else { throw KeychainError(status: addStatus) }
        } else if status != errSecSuccess {
            throw KeychainError(status: status)
        }
    }

    func data(for account: String) throws -> Data? {
        let query: [String: Any] = [
            kSecClass as String: kSecClassGenericPassword,
            kSecAttrService as String: service,
            kSecAttrAccount as String: account,
            kSecReturnData as String: true,
            kSecMatchLimit as String: kSecMatchLimitOne,
        ]
        var result: AnyObject?
        let status = SecItemCopyMatching(query as CFDictionary, &result)
        switch status {
        case errSecSuccess: return result as? Data
        case errSecItemNotFound: return nil
        default: throw KeychainError(status: status)
        }
    }

    func delete(_ account: String) throws {
        let query: [String: Any] = [
            kSecClass as String: kSecClassGenericPassword,
            kSecAttrService as String: service,
            kSecAttrAccount as String: account,
        ]
        let status = SecItemDelete(query as CFDictionary)
        guard status == errSecSuccess || status == errSecItemNotFound else { throw KeychainError(status: status) }
    }
}

Token store

actor TokenStore: TokenProviding {
    private let keychain: KeychainStore
    private let baseURL: URL
    private var cachedAccessToken: String?           // memory only

    init(keychain: KeychainStore, baseURL: URL) {
        self.keychain = keychain
        self.baseURL = baseURL
    }

    /// Keychain items survive app deletion. Clear them on the first launch of a fresh install.
    static func wipeIfFreshInstall(_ keychain: KeychainStore, defaults: UserDefaults = .standard) {
        let key = "hasLaunchedBefore"
        guard !defaults.bool(forKey: key) else { return }
        try? keychain.delete("refreshToken")
        defaults.set(true, forKey: key)
    }

    func accessToken() async -> String? { cachedAccessToken }

    func store(_ pair: TokenPair) throws {
        try keychain.set(Data(pair.refreshToken.utf8), for: "refreshToken")
        cachedAccessToken = pair.accessToken
    }

    func refresh() async throws -> String {
        guard let refreshToken = try storedRefreshToken() else { throw APIError.sessionExpired }

        let request = try postRequest(path: "/v1/auth/refresh", body: ["refreshToken": refreshToken])
        let (body, response) = try await URLSession.shared.data(for: request) // network errors propagate: don't sign out offline users
        guard let http = response as? HTTPURLResponse else { throw APIError.unexpectedStatus(-1, requestId: nil) }
        if http.statusCode == 401 || http.statusCode == 400 {
            try? keychain.delete("refreshToken")
            cachedAccessToken = nil
            throw APIError.sessionExpired
        }
        guard (200..<300).contains(http.statusCode) else { throw APIError.unexpectedStatus(http.statusCode, requestId: nil) }

        let pair = try JSONDecoder.api.decode(TokenPair.self, from: body)
        try store(pair)                                   // rotation: persist the new refresh token
        return pair.accessToken
    }

    /// Revokes the server session with the refresh token (works even if the access token expired), then wipes local state.
    func revokeAndClear() async {
        if let refreshToken = try? storedRefreshToken(),
           let request = try? postRequest(path: "/v1/auth/logout", body: ["refreshToken": refreshToken]) {
            _ = try? await URLSession.shared.data(for: request)   // best effort: we may be offline
        }
        try? keychain.delete("refreshToken")
        cachedAccessToken = nil
    }

    private func storedRefreshToken() throws -> String? {
        try keychain.data(for: "refreshToken").flatMap { String(data: $0, encoding: .utf8) }
    }

    private func postRequest(path: String, body: [String: String]) throws -> URLRequest {
        var request = URLRequest(url: baseURL.appending(path: path))
        request.httpMethod = "POST"
        request.setValue("application/json", forHTTPHeaderField: "Content-Type")
        request.httpBody = try JSONEncoder.api.encode(body)
        return request
    }
}

struct TokenPair: Codable, Sendable {
    let accessToken: String
    let refreshToken: String
}

UserDefaults is a required-reason API. Declare it in PrivacyInfo.xcprivacy (reason CA92.1 for app-only defaults).

Session model

@MainActor @Observable
final class SessionModel {
    enum Status { case restoring, signedOut, signedIn }
    private(set) var status: Status = .restoring

    private let tokens: TokenStore

    init(tokens: TokenStore) {
        self.tokens = tokens
    }

    func restore() async {
        do {
            _ = try await tokens.refresh()
            status = .signedIn
        } catch APIError.sessionExpired {
            status = .signedOut
        } catch {
            status = .signedIn  // offline: keep the user in, show cached data and an offline banner
        }
    }

    func signOut() async {
        await tokens.revokeAndClear()
        URLCache.shared.removeAllCachedResponses()
        // also clear SwiftData/GRDB caches and in-memory models that hold user data
        status = .signedOut
    }
}

Call SessionModel.restore() from a .task on the root view. While the status is .restoring, keep showing the launch UI. When any request fails with APIError.sessionExpired, route it to SessionModel.signOut(), for example through an AsyncStream the APIClient publishes, so a revoked session signs out on every screen.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts4d3 checks · Risk SAFE
  • Gen Agent Trust Hub4d

    The skill provides architectural guidelines and reference implementations for building secure, production-ready iOS applications using Swift and SwiftUI. It emphasizes best practices such as secure credential storage in the Keychain, server-side purchase verification, and robust concurrency management. No security risks were identified.

  • Socket4d

    No alerts

  • Snyk4d

    Risk: LOW · No issues

Signed by skilld at 920a44a. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last month.

Steadyupdated 2 months ago
metadata
{
  "author": "suleyman",
  "version": "1.0.0"
}

README badge

README badge for suleyman/fullstack-agent-skills/swift-ios