Kit

Sources/Packages/Sources/SecretAgentKit/SSHAgentProtocol.swift

@@ -1,9 +1,11 @@
 import Foundation
 
+/// A namespace for the SSH Agent Protocol, as described in https://tools.ietf.org/id/draft-miller-ssh-agent-01.html
 public enum SSHAgent {}
 
 extension SSHAgent {
 
+    /// The type of the SSH Agent Request, as described in https://tools.ietf.org/id/draft-miller-ssh-agent-01.html#rfc.section.5.1
     public enum RequestType: UInt8, CustomDebugStringConvertible {
         case requestIdentities = 11
         case signRequest = 13
@@ -18,6 +20,7 @@ extension SSHAgent {
         }
     }
 
+    /// The type of the SSH Agent Response, as described in https://tools.ietf.org/id/draft-miller-ssh-agent-01.html#rfc.section.5.1
     public enum ResponseType: UInt8, CustomDebugStringConvertible {
         case agentFailure = 5
         case agentIdentitiesAnswer = 12

Sources/Packages/Sources/SecretAgentKit/SigningRequestTracer.swift

@@ -4,11 +4,15 @@ import Security
 import SecretKit
 import SecretAgentKitHeaders
 
+/// An object responsible for generating ``SecretKit.SigningRequestProvenance`` objects.
 struct SigningRequestTracer {
 }
 
 extension SigningRequestTracer {
 
+    /// Generates a ``SecretKit.SigningRequestProvenance`` from a ``FileHandleReader``.
+    /// - Parameter fileHandleReader: The reader involved in processing the request.
+    /// - Returns: A ``SecretKit.SigningRequestProvenance`` describing the origin of the request.
     func provenance(from fileHandleReader: FileHandleReader) -> SigningRequestProvenance {
         let firstInfo = process(from: fileHandleReader.pidOfConnectedProcess)
 
@@ -19,6 +23,9 @@ extension SigningRequestTracer {
         return provenance
     }
 
+    /// Generates a `kinfo_proc` representation of the provided process ID.
+    /// - Parameter pid: The process ID to look up.
+    /// - Returns: a `kinfo_proc` struct describing the process ID.
     func pidAndNameInfo(from pid: Int32) -> kinfo_proc {
         var len = MemoryLayout<kinfo_proc>.size
         let infoPointer = UnsafeMutableRawPointer.allocate(byteCount: len, alignment: 1)
@@ -27,6 +34,9 @@ extension SigningRequestTracer {
         return infoPointer.load(as: kinfo_proc.self)
     }
 
+    /// Generates a ``SecretKit.SigningRequestProvenance.Process`` from a provided process ID.
+    /// - Parameter pid: The process ID to look up.
+    /// - Returns: A ``SecretKit.SigningRequestProvenance.Process`` describing the process.
     func process(from pid: Int32) -> SigningRequestProvenance.Process {
         var pidAndNameInfo = self.pidAndNameInfo(from: pid)
         let ppid = pidAndNameInfo.kp_eproc.e_ppid != 0 ? pidAndNameInfo.kp_eproc.e_ppid : nil
@@ -41,6 +51,9 @@ extension SigningRequestTracer {
         return SigningRequestProvenance.Process(pid: pid, processName: procName, appName: appName(for: pid), iconURL: iconURL(for: pid), path: path, validSignature: valid, parentPID: ppid)
     }
 
+    /// Looks up the URL for the icon of a process ID, if it has one.
+    /// - Parameter pid: The process ID to look up.
+    /// - Returns: A URL to the icon, if the process has one.
     func iconURL(for pid: Int32) -> URL? {
         do {
             if let app = NSRunningApplication(processIdentifier: pid), let icon = app.icon?.tiffRepresentation {
@@ -54,6 +67,9 @@ extension SigningRequestTracer {
         return nil
     }
 
+    /// Looks up the application name of a process ID, if it has one.
+    /// - Parameter pid: The process ID to look up.
+    /// - Returns: The process's display name, if the process has one.
     func appName(for pid: Int32) -> String? {
         NSRunningApplication(processIdentifier: pid)?.localizedName
     }

Sources/Packages/Sources/SecretAgentKit/SigningWitness.swift

@@ -1,9 +1,23 @@
 import Foundation
 import SecretKit
 
+/// A protocol that allows conformers to be notified of access to secrets, and optionally prevent access.
 public protocol SigningWitness {
 
+    /// A ridiculously named method that notifies the callee that a signing operation is about to be performed using a secret. The callee may `throw` an `Error` to prevent access from occurring.
+    /// - Parameters:
+    ///   - secret: The ``SecretKit.Secret`` that will be used to sign the request.
+    ///   - store: The ``SecretKit.Store`` being asked to sign the request..
+    ///   - provenance: A ``SecretKit.SigningRequestProvenance`` object describing the origin of the request.
+    ///   - Note: This method being called does not imply that the requst has been authorized. If a secret requires authentication, authentication will still need to be performed by the user before the request will be performed. If the user declines or fails to authenticate, the request will fail.
     func speakNowOrForeverHoldYourPeace(forAccessTo secret: AnySecret, from store: AnySecretStore, by provenance: SigningRequestProvenance) throws
+
+    /// Notifies the callee that a signing operation has been performed for a given secret.
+    /// - Parameters:
+    ///   - secret: The ``SecretKit.Secret`` that will was used to sign the request.
+    ///   - store: The ``SecretKit.Store`` that signed the request..
+    ///   - provenance: A ``SecretKit.SigningRequestProvenance`` object describing the origin of the request.
+    ///   - requiredAuthentication: A boolean describing whether or not authentication was required for the request.
     func witness(accessTo secret: AnySecret, from store: AnySecretStore, by provenance: SigningRequestProvenance, requiredAuthentication: Bool) throws
 
 }

Sources/SecretAgent/Notifier.swift

@@ -103,9 +103,20 @@ class Notifier {
 
 extension Notifier: SigningWitness {
 
+    /// <#Description#>
+    /// - Parameters:
+    ///   - secret: <#secret description#>
+    ///   - store: <#store description#>
+    ///   - provenance: <#provenance description#>
     func speakNowOrForeverHoldYourPeace(forAccessTo secret: AnySecret, from store: AnySecretStore, by provenance: SigningRequestProvenance) throws {
     }
 
+    /// <#Description#>
+    /// - Parameters:
+    ///   - secret: <#secret description#>
+    ///   - store: <#store description#>
+    ///   - provenance: <#provenance description#>
+    ///   - requiredAuthentication: <#requiredAuthentication description#>
     func witness(accessTo secret: AnySecret, from store: AnySecretStore, by provenance: SigningRequestProvenance, requiredAuthentication: Bool) throws {
         notify(accessTo: secret, from: store, by: provenance, requiredAuthentication: requiredAuthentication)
     }