The PIN, the Keychain, and the Wire

"A secret's home is the OS keystore. Not a config file, not a log line, not a constant in your source."

The Secret Has a Home, and It's Not Your Code

When Flint reaches a brain running on another machine, that call is authenticated — and authentication means a secret. The first rule of a secret is where it lives: in the macOS Keychain, the operating system's protected store, and nowhere else. Not hardcoded in the source, not written to the macros file, not printed to a log, not committed to a repo. A private repo does not change this — 'it's private' is not a place to keep a live secret. The Keychain exists precisely so an app never has to hold a durable secret in its own files or code.

Keychain for the Durable, Memory for the Session

There are two secrets with two lifetimes, and they live in two places accordingly. The durable one — the PIN the user set — lives in the Keychain, retrieved only when needed and never copied elsewhere. From it, Flint mints a short-lived session token, and that token lives only in memory for the length of the session; it is never persisted. Matching the storage to the lifetime is the discipline: durable secret in the protected keystore, ephemeral token in RAM that vanishes when the app quits. Neither ever touches disk in plaintext.

SECRET            LIFETIME      HOME
----------------  ------------  ------------------------
the PIN           durable       macOS Keychain (protected)
session token     ephemeral     memory only (never persisted)

Never: hardcoded, logged, in a config file, in the repo.

A Private Wire

The transport matters too. Remote calls travel over a private network overlay rather than the open internet, so the wire itself is not publicly reachable, and the session header rides that private connection. The combination — a secret held in the Keychain, a short-lived token in memory, over a private wire — is a layered posture: even the network path is not exposed, so the header isn't crossing the public internet to begin with. Each layer assumes the others might fail and adds protection anyway.

Store secrets in the OS keystore; scope tokens to memory; never let either reach disk in plaintext. This is the boring, correct pattern, and boring is what you want for secrets. The durable credential goes in the platform's protected store, the session credential lives only as long as the session in memory, and neither is ever hardcoded, logged, or serialized to a file. When you find yourself about to write a secret into a config or a constant 'just for now,' that's the moment the pattern is there to stop.

This lesson teaches the pattern and never a parameter. You'll notice there's no actual PIN here, no real token, no reachable remote address — deliberately. Auth content is exactly the kind of thing where the shape is the lesson and the specific values are dangerous to write down. The takeaway is the structure: Keychain for the durable secret, memory for the session, a private wire for the transport. A real value in a lesson is a leak; the pattern is the teachable, shareable part.

Code

The durable secret lives in the Keychain — never in code·swift

import Security

// Load the PIN from the macOS Keychain. It is never hardcoded, logged,
// or written to a file. 'flint-remote' / 'pippa-pin' are lookup keys,
// not the secret itself.
func loadPIN() -> String? {
    let query: [String: Any] = [
        kSecClass as String: kSecClassGenericPassword,
        kSecAttrService as String: "flint-remote",
        kSecAttrAccount as String: "pippa-pin",
        kSecReturnData as String: true,
        kSecMatchLimit as String: kSecMatchLimitOne,
    ]
    var item: CFTypeRef?
    guard SecItemCopyMatching(query as CFDictionary, &item) == errSecSuccess,
          let data = item as? Data else { return nil }
    return String(data: data, encoding: .utf8)   // used, never printed
}

// The session token is minted from the PIN and kept in memory ONLY.
final class RemoteSession {
    private var token: String?          // in-memory; never persisted
    func attach(to request: inout URLRequest) {
        request.setValue(token, forHTTPHeaderField: "X-Pippa-Session")
    }
}

Exercise

Someone proposes storing the remote PIN in the same JSON file as the macros 'so it's all in one place,' arguing the repo is private anyway. Refute it with the specific risks, and lay out the correct storage for each of: the durable PIN, the session token, and the network transport. Then explain why an auth lesson should teach the pattern but never include a real PIN or reachable address.

Hint

The macros file is plaintext on disk, gets backed up and synced, and 'private repo' still means the secret is one leak or one misplaced copy from exposure — private is not a vault. Correct storage: PIN in the Keychain, session token in memory only, transport over a private network overlay. An auth lesson omits real values because the structure is what transfers and is safe to share, while a concrete PIN or address is a live credential and a reachable target — writing it down turns a lesson into a leak.

The PIN, the Keychain, and the Wire

The Secret Has a Home, and It's Not Your Code

Keychain for the Durable, Memory for the Session

A Private Wire

Code

External links

Exercise

Progress

Comments 0