buzz/mobile/ios/BuzzPushKit/Sources/BuzzPushKit/BuzzPushTranscript.swift

import Foundation

/// Errors thrown by the canonical transcript encoder.
public enum BuzzPushTranscriptError: Error, Equatable {
    /// A string field contained non-ASCII scalars. Buzz push admits only ASCII
    /// authority-bearing strings; rather than guess at UTF-8-vs-escaping
    /// behavior we fail closed.
    case nonASCIIInput(field: String)
    /// The configured gateway was not an HTTP or HTTPS origin.
    case invalidGatewayOrigin
}

/// Canonical Buzz push App Attest transcript encoder.
///
/// Buzz push pins the exact bytes
/// every App Attest operation signs:
///
///     <domain> + "\n" + <compact ordered JSON object>
///
/// The JSON object has no insignificant whitespace, members appear in a fixed
/// per-route order, integers use shortest decimal notation, and strings use
/// minimal JSON escaping (quotation mark, reverse solidus, U+0000..U+001F).
/// The gateway builds the same bytes with serde_json and compares hashes, so
/// any byte difference is a silent `401 invalid_attestation`. This encoder is
/// hand-rolled for that reason: `JSONSerialization` escapes `/` as `\/` and
/// does not guarantee member order, so it must never be used for transcripts.
///
/// Ground truth: `crates/buzz-push-gateway/tests/vectors/app_attest_transcripts.json`,
/// generated and asserted by the gateway's own encoder. The tests in this
/// package replay those vectors byte-for-byte.
///
/// The `audience` member uses the fixed origin and route registered by NIP-PL
/// v1. A configurable gateway origin changes transport routing, not these
/// protocol bytes.
public enum BuzzPushTranscript {
    // MARK: Domains

    public static let enrollDomain = "buzz.push.enroll.v1"
    public static let delegateDomain = "buzz.push.delegate.v1"
    public static let rotateEndpointDomain = "buzz.push.rotate-endpoint.v1"
    public static let revokeDelegationDomain = "buzz.push.revoke-delegation.v1"
    public static let revokeInstallationDomain = "buzz.push.revoke-installation.v1"

    /// Wire version for buzz-push-v1. Every transcript carries `"v":1`.
    public static let wireVersion: Int64 = 1

    /// Origin registered by NIP-PL v1 for every App Attest transcript audience.
    private static let registeredAudienceOrigin = "https://push.buzz.xyz"

    // MARK: Transcripts

    /// `buzz.push.enroll.v1` — these exact bytes are the App Attest
    /// `clientData` supplied to attestation verification.
    public static func enroll(
        gatewayOrigin: URL,
        challengeId: UUID,
        challenge: String,
        keyId: String,
        endpoint: String,
        endpointEpoch: Int64,
        expiresAt: Int64
    ) throws -> Data {
        var o = CanonicalObject()
        o.int("v", wireVersion)
        try o.string("audience", audience(gatewayOrigin, route: "v1/installations"))
        o.uuid("challenge_id", challengeId)
        try o.string("challenge", challenge, field: "challenge")
        try o.string("key_id", keyId, field: "key_id")
        try o.string("endpoint", endpoint, field: "endpoint")
        o.int("endpoint_epoch", endpointEpoch)
        o.int("expires_at", expiresAt)
        return encode(domain: enrollDomain, object: o)
    }

    /// `buzz.push.delegate.v1` — `SHA-256(bytes)` is the assertion
    /// `clientDataHash`.
    public static func delegate(
        gatewayOrigin: URL,
        challengeId: UUID,
        challenge: String,
        installationHandle: UUID,
        endpointEpoch: Int64,
        generation: Int64,
        relayPubkey: String,
        notBefore: Int64,
        expiresAt: Int64
    ) throws -> Data {
        var o = CanonicalObject()
        o.int("v", wireVersion)
        try o.string("audience", audience(gatewayOrigin, route: "v1/delegations"))
        o.uuid("challenge_id", challengeId)
        try o.string("challenge", challenge, field: "challenge")
        o.uuid("installation_handle", installationHandle)
        o.int("endpoint_epoch", endpointEpoch)
        o.int("generation", generation)
        try o.string("relay_pubkey", relayPubkey, field: "relay_pubkey")
        o.int("not_before", notBefore)
        o.int("expires_at", expiresAt)
        return encode(domain: delegateDomain, object: o)
    }

    /// `buzz.push.rotate-endpoint.v1` — `SHA-256(bytes)` is the assertion
    /// `clientDataHash`.
    public static func rotateEndpoint(
        gatewayOrigin: URL,
        challengeId: UUID,
        challenge: String,
        installationHandle: UUID,
        endpointEpoch: Int64,
        newEndpointEpoch: Int64,
        endpoint: String
    ) throws -> Data {
        var o = CanonicalObject()
        o.int("v", wireVersion)
        try o.string(
            "audience",
            audience(gatewayOrigin, route: "v1/installations/endpoint")
        )
        o.uuid("challenge_id", challengeId)
        try o.string("challenge", challenge, field: "challenge")
        o.uuid("installation_handle", installationHandle)
        o.int("endpoint_epoch", endpointEpoch)
        o.int("new_endpoint_epoch", newEndpointEpoch)
        try o.string("endpoint", endpoint, field: "endpoint")
        return encode(domain: rotateEndpointDomain, object: o)
    }

    /// `buzz.push.revoke-delegation.v1` — `SHA-256(bytes)` is the assertion
    /// `clientDataHash`.
    public static func revokeDelegation(
        gatewayOrigin: URL,
        challengeId: UUID,
        challenge: String,
        installationHandle: UUID,
        relayPubkey: String,
        generation: Int64
    ) throws -> Data {
        var o = CanonicalObject()
        o.int("v", wireVersion)
        try o.string(
            "audience",
            audience(gatewayOrigin, route: "v1/delegations/revoke")
        )
        o.uuid("challenge_id", challengeId)
        try o.string("challenge", challenge, field: "challenge")
        o.uuid("installation_handle", installationHandle)
        try o.string("relay_pubkey", relayPubkey, field: "relay_pubkey")
        o.int("generation", generation)
        return encode(domain: revokeDelegationDomain, object: o)
    }

    /// `buzz.push.revoke-installation.v1` — `SHA-256(bytes)` is the assertion
    /// `clientDataHash`.
    public static func revokeInstallation(
        gatewayOrigin: URL,
        challengeId: UUID,
        challenge: String,
        installationHandle: UUID,
        endpointEpoch: Int64,
        newEndpointEpoch: Int64
    ) throws -> Data {
        var o = CanonicalObject()
        o.int("v", wireVersion)
        try o.string(
            "audience",
            audience(gatewayOrigin, route: "v1/installations/revoke")
        )
        o.uuid("challenge_id", challengeId)
        try o.string("challenge", challenge, field: "challenge")
        o.uuid("installation_handle", installationHandle)
        o.int("endpoint_epoch", endpointEpoch)
        o.int("new_endpoint_epoch", newEndpointEpoch)
        return encode(domain: revokeInstallationDomain, object: o)
    }

    // MARK: Internals

    private static func encode(domain: String, object: CanonicalObject) -> Data {
        Data((domain + "\n" + object.encoded()).utf8)
    }

    /// Validates and canonicalizes a configured gateway origin.
    public static func canonicalGatewayOrigin(_ value: URL) throws -> (url: URL, text: String) {
        guard let scheme = value.scheme?.lowercased(),
            scheme == "http" || scheme == "https",
            let host = value.host?.lowercased(),
            value.path.isEmpty || value.path == "/",
            value.user == nil,
            value.password == nil,
            value.query == nil,
            value.fragment == nil
        else {
            throw BuzzPushTranscriptError.invalidGatewayOrigin
        }
        var components = URLComponents()
        components.scheme = scheme
        components.host = host
        components.port = value.port
        guard let url = components.url, let text = components.string else {
            throw BuzzPushTranscriptError.invalidGatewayOrigin
        }
        return (url, text)
    }

    private static func audience(_ gatewayOrigin: URL, route: String) throws -> String {
        _ = try canonicalGatewayOrigin(gatewayOrigin)
        return "\(registeredAudienceOrigin)/\(route)"
    }

    /// Ordered compact JSON object writer. Emission order == call order;
    /// there is deliberately no sorting, no whitespace, and no `Encodable`
    /// round-trip anywhere near these bytes.
    struct CanonicalObject {
        private var members: [String] = []

        mutating func int(_ key: String, _ value: Int64) {
            // Swift's Int64 description is shortest decimal notation, which
            // is what the spec pins and what serde_json emits.
            members.append("\"\(key)\":\(value)")
        }

        mutating func uuid(_ key: String, _ value: UUID) {
            // Canonical lowercase-hyphenated form, matching uuid::Uuid's
            // serde serialization. Foundation's uuidString is uppercase.
            members.append("\"\(key)\":\"\(value.uuidString.lowercased())\"")
        }

        mutating func string(_ key: String, _ value: String, field: String? = nil) throws {
            members.append("\"\(key)\":\"\(try Self.escape(value, field: field ?? key))\"")
        }

        func encoded() -> String {
            "{" + members.joined(separator: ",") + "}"
        }

        /// Minimal JSON string escaping, byte-identical to serde_json:
        /// `"` and `\` get two-character escapes; U+0008, U+0009, U+000A,
        /// U+000C, U+000D get their short forms; the remaining C0 controls
        /// get lowercase `\u00xx`. Nothing else is escaped (in particular
        /// `/` is NOT escaped — the JSONSerialization behavior that makes it
        /// unusable here). Non-ASCII input is rejected outright.
        static func escape(_ s: String, field: String) throws -> String {
            var out = String()
            out.reserveCapacity(s.count)
            for scalar in s.unicodeScalars {
                switch scalar.value {
                case 0x22: out += "\\\""
                case 0x5C: out += "\\\\"
                case 0x08: out += "\\b"
                case 0x09: out += "\\t"
                case 0x0A: out += "\\n"
                case 0x0C: out += "\\f"
                case 0x0D: out += "\\r"
                case 0x00...0x1F: out += String(format: "\\u%04x", scalar.value)
                case 0x20...0x7E: out.unicodeScalars.append(scalar)
                default: throw BuzzPushTranscriptError.nonASCIIInput(field: field)
                }
            }
            return out
        }
    }
}