@sriinnu/runic 1.2.0 → 2.11.1

package/Packages/Silo/README.md

@@ -1,466 +0,0 @@
-# Silo 🏺
-
-<p align="center">
-  <img src="Assets/silo-logo.svg" alt="Silo logo" width="180" />
-</p>
-<p align="center">
-  <em>Small-size mark: <code>Assets/silo-mark.svg</code></em>
-</p>
-
-**Cross-platform browser cookie storage extraction**
-
-Silo is a Swift library for reading browser cookies across macOS, iOS, Linux, and Windows. Extract cookies from Safari, Chrome, Firefox, Edge, Brave, Arc, and more with a modern, type-safe API.
-
-## ✨ Features
-
-### Core Capabilities
-- 🌍 **Multi-platform** – macOS, Linux, Windows, iOS (app container only)
-- 🌐 **Multi-browser** – Safari, Chrome, Chromium, Firefox, Edge, Brave, Arc, Vivaldi, Helium, ChatGPT Atlas, and more
-- 👤 **Profile-aware** – Multiple browser profile support with automatic detection
-- 🔍 **Query filtering** – Domain/path/expiry/flag filtering plus optional domain/path regex filtering
-- 🔐 **Decryption** – macOS Keychain + Local State, Windows DPAPI, Linux Secret Service + "peanuts" fallback
-- 🧯 **Decryption policy** – Best-effort or strict failure behavior
-- 🧹 **Redaction** – Safe logging via `BrowserCookieRecord.redactedValue`
-- 🍪 **HTTPCookie** – Direct Foundation integration for seamless URLSession usage
-- 🧾 **JSON import/export** – Round-trip normalized cookies for external tooling
-- 📈 **Analytics + sync helpers** – Summarize and diff cookie sets (no write-back)
-- 📊 **Normalized attributes** – Domain, path, expiry, secure/httpOnly, host-only, SameSite, priority, and partitioning when available
-
-**What It Does**
-- Reads local browser cookie stores for supported browsers and profiles.
-- Decrypts Chromium cookies using platform keychains or explicit keys.
-- Normalizes cookies into `BrowserCookieRecord` and `HTTPCookie`.
-- Filters by domain/path/expiry/flags and optional regex patterns.
-
-**What It Does Not Do**
-- It is read-only: no cookie CRUD or write-back to browser stores.
-- Sync helpers are analysis-only and do not apply changes.
-- It does not bypass OS permissions or sandboxing.
-- It does not expose Safari/WebKit SameSite values yet.
-
-## Status
-- Implemented: core models, query filtering, HTTPCookie mapping (host-only + SameSite where available), JSON import/export, analytics + sync helpers, mock store CRUD for tests, macOS/Linux/Windows readers, iOS app-container reader, Linux Secret Service lookup (explicit key override + opt-in peanuts fallback), Windows DPAPI key handling.
-- Planned: deeper keyring integration and expanded iOS entitlements guidance.
-- See `TODO.md` for the working backlog.
-Note: Linux decryption uses Secret Service when available; the "peanuts" fallback is disabled unless `SILO_ALLOW_INSECURE_CHROMIUM_FALLBACK=1` is set. On iOS, only WebKit/Safari app-container cookies are discoverable unless you pass App Group containers.
-
-## Roadmap
-- Browser store write-back (CRUD) with encryption support
-- Deeper Linux keyring/libsecret coverage
-- Safari SameSite support if WebKit exposes it
-
-## 📦 Installation
-
-```swift
-dependencies: [
-    .package(url: "https://github.com/sriinnu/Silo.git", from: "1.0.0")
-]
-```
-
-## ✅ Getting Started (Permissions + Setup)
-
-### macOS
-- Enable **Full Disk Access** for apps reading Safari cookies.
-- Allow **Keychain** access when prompted for Chromium decryption.
-- Optional: set `SILO_CHROME_SAFE_STORAGE` to override the keychain password.
-
-### Linux
-- Install and enable `secret-tool` (libsecret) for Chromium decryption.
-- Silo resolves `secret-tool` from `SILO_SECRET_TOOL_PATH` (authoritative), well-known locations, or `PATH`.
-- `secret-tool` lookups use a short timeout (default 2000ms); override with `SILO_SECRET_TOOL_TIMEOUT_MS` or set it to `0` to disable.
-- If keyring is unavailable or locked, set `SILO_CHROME_SAFE_STORAGE` or enable the insecure fallback with `SILO_ALLOW_INSECURE_CHROMIUM_FALLBACK=1`.
-
-### Windows
-- Run as the same Windows user who owns the browser profile.
-- Ensure access to the `Local State` file and profile database (DPAPI is user-bound).
-- AES-GCM cookies (`v10`/`v11`) require a readable `Local State` key; legacy DPAPI cookies can still decrypt without it.
-
-### iOS
-- Reads **only** WebKit/Safari app-container cookies.
-- Shared container access requires App Group entitlements and explicit container configuration.
-
-### Quick Permissions Checklist
-
-| Platform | Required Access | Notes |
-|---------|------------------|-------|
-| macOS | Full Disk Access (Safari), Keychain | Safari cookies live in protected locations. |
-| Linux | Secret Service / libsecret | `secret-tool` required for Chromium decryption. |
-| Windows | DPAPI (user profile) | Must run as the same Windows user. |
-| iOS | App container + entitlements | WebKit/Safari only; App Groups required for shared containers. |
-
-## 🚀 Quick Start
-
-```swift
-import Silo
-
-let client = BrowserCookieClient(
-    configuration: .init(decryptionFailurePolicy: .strict)
-)
-
-// List available profiles
-let stores = client.stores(for: .chrome)
-
-// Query cookies
-let query = BrowserCookieQuery(
-    domains: ["example.com"],
-    domainMatch: .suffix
-)
-
-// Get records (grouped by store)
-let sources = try client.records(matching: query, in: .chrome)
-let records = sources.flatMap { $0.records }
-for record in records {
-    print(record.redactedValue)
-}
-
-// Convert to HTTPCookie
-let cookies = try client.cookies(matching: query, in: .chrome)
-
-// Export to JSON
-let exportData = try client.exportJSON(matching: query, in: .chrome)
-```
-
-## 🌍 Platform Support
-
-| Browser | macOS | Linux | Windows | iOS |
-|---------|-------|-------|---------|-----|
-| Safari (WebKit) | read | - | - | read (app container) |
-| Chrome (Stable/Beta/Canary) | read | read | read | - |
-| Chromium | read | read | read | - |
-| Firefox | read | read | read | - |
-| Edge (Stable/Beta/Canary) | read | read | read | - |
-| Brave (Stable/Beta/Nightly) | read | read | read | - |
-| Arc (Stable/Beta/Canary) | read | - | - | - |
-| Vivaldi | read | read | read | - |
-| Helium | read | read | read | - |
-| ChatGPT Atlas | read | - | - | - |
-
-Status legend: read = cookie reading implemented; discovery = profile/store detection only; planned = not implemented yet.
-Notes: Safari/WebKit `Cookies.binarycookies` parsing does not currently expose SameSite, so `sameSite` is always `nil` for Safari/WebKit records. Regex filtering applies to `domainPattern` and `pathPattern` when `useRegex` is `true`; non-regex path matching uses `contains`/`prefix`/`exact`.
-
-**Limitations**
-- Safari/WebKit SameSite is not available from `Cookies.binarycookies` yet.
-- iOS is limited to WebKit/Safari app-container cookies only.
-- Linux keyring availability varies; you may need explicit keys or fallback settings.
-- Real-world Safari binarycookies parsing still needs broader validation.
-
-## 📝 API
-
-### Query Filtering
-
-```swift
-// Exact match
-let exactQuery = BrowserCookieQuery(
-    domains: ["api.example.com"],
-    domainMatch: .exact
-)
-
-// Multiple domains
-let multiQuery = BrowserCookieQuery(
-    domains: ["example.com", "example.org"],
-    domainMatch: .suffix
-)
-
-// Regex domain match
-let regexDomainQuery = BrowserCookieQuery(
-    domainPattern: ".*\\.example\\.com$",
-    useRegex: true
-)
-
-// Include expired
-let allQuery = BrowserCookieQuery(
-    domains: ["example.com"],
-    includeExpired: true
-)
-
-// Regex path match
-let apiQuery = BrowserCookieQuery(
-    pathPattern: "^/api/",
-    useRegex: true
-)
-```
-
-### Browser Selection
-
-```swift
-// Specific browser
-let cookies = try client.cookies(matching: query, in: .chrome)
-
-// Multiple browsers
-let allCookies = try client.cookies(
-    matching: query,
-    in: [.chrome, .firefox, .safari]
-)
-```
-
-### JSON Export
-
-```swift
-let export = try client.export(matching: query, in: .chrome)
-let json = try export.jsonData()
-```
-
-### JSON Import
-
-```swift
-let data = try Data(contentsOf: url)
-let imported = try client.importJSON(data)
-let importedRecords = imported.records
-
-// If the payload does not include host-only metadata:
-let relaxedImport = try client.importJSON(
-    data,
-    options: BrowserCookieImportOptions(defaultHostOnly: false)
-)
-```
-
-### JSON Schema Version
-
-`BrowserCookieExport` embeds a `schemaVersion` (currently `1`) so payloads can evolve safely.
-
-### Analytics + Sync Helpers
-
-```swift
-let analytics = BrowserCookieAnalytics(records: records)
-print(analytics.totalCount)
-
-let plan = BrowserCookieSync.plan(existing: records, incoming: importedRecords)
-if plan.hasChanges {
-    print("Adds: \(plan.additions.count), Updates: \(plan.updates.count)")
-}
-```
-
-### Mock Store (In-Memory CRUD)
-
-```swift
-let mockStore = BrowserCookieMockStore(browser: .chrome, label: "Mock")
-let record = BrowserCookieRecord(
-    domain: "example.com",
-    name: "sid",
-    path: "/",
-    value: "abc",
-    expires: nil,
-    isSecure: true,
-    isHTTPOnly: true)
-
-try mockStore.create(record)
-try mockStore.update(record)
-mockStore.upsert(record)
-_ = mockStore.delete(record)
-```
-
-## 🔐 Permissions
-
-### macOS
-- **Full Disk Access** for Safari
-- **Keychain** for Chromium encrypted cookies
-
-### Linux
-- **Keyring access** for encrypted cookies
-- **File permissions** for profiles
-
-### Windows
-- **DPAPI** for encrypted cookies
-
-### iOS
-- **App container** access
-- **App Groups** entitlements for shared containers
-
-### iOS Entitlements (App Groups)
-Silo can only read WebKit/Safari cookies from the current app container or App Group containers you own. It cannot access system Safari cookies or other apps.
-To read from a shared container:
-- Enable App Groups in Xcode for all participating targets.
-- Add `com.apple.security.application-groups` with the same group identifier(s).
-- Pass the App Group container URL(s) to `BrowserCookieClient.Configuration(homeDirectories:)`.
-
-```swift
-let groupURL = FileManager.default.containerURL(
-    forSecurityApplicationGroupIdentifier: "group.com.example.cookies"
-)
-let client = BrowserCookieClient(
-    configuration: .init(homeDirectories: [groupURL].compactMap { $0 })
-)
-```
-
-## Security
-Silo reads sensitive cookie data. Apply least privilege and avoid logging cookie values.
-Use `BrowserCookieRecord.redactedValue` to safely log cookie data. For strict
-decryption failures, set `BrowserCookieClient.Configuration(decryptionFailurePolicy: .strict)`.
-On Linux, the insecure "peanuts" fallback is disabled by default. To enable it, set
-`SILO_ALLOW_INSECURE_CHROMIUM_FALLBACK=1` (not recommended). For explicit keys, set
-`SILO_CHROME_SAFE_STORAGE`. See `SECURITY.md`.
-
-### Keyring Hardening
-Linux hardening:
-- Prefer `SILO_SECRET_TOOL_PATH` to pin the `secret-tool` location.
-- `SILO_SECRET_TOOL_TIMEOUT_MS` limits keyring lookups (default 2000ms; set `0` to disable).
-- Use `SILO_CHROME_SAFE_STORAGE` for explicit keys and only enable the peanuts fallback when you accept the risk.
-
-Windows hardening:
-- DPAPI decryption is non-interactive; run inside the target user session.
-- AES-GCM cookies (`v10`/`v11`) require a readable `Local State` key file.
-
-## Testing
-
-```bash
-swift test
-```
-
-Integration tests build real SQLite cookie stores on disk and validate:
-- Chromium + Firefox readers (plain value parsing)
-- Safari binarycookies parsing
-- Chromium decryption paths (AES-GCM on macOS/Linux, AES-CBC on Linux, DPAPI-wrapped key on Windows)
-
-## Publishing
-
-### Git (Release Tags)
-```bash
-git tag v1.0.0
-git push --tags
-```
-
-### NPM (Optional Metadata Wrapper)
-```bash
-npm publish --access public
-```
-
-Notes:
-- The npm package is a lightweight metadata wrapper pointing to the Swift package.
-- Update the version in `package.json` when tagging a new release.
-
-## 📚 Documentation
-
-```bash
-swift package generate-documentation --target Silo
-```
-
-## 📚 API Reference
-
-### BrowserCookieClient
-
-```swift
-public struct BrowserCookieClient {
-    // Initialize
-    public init(configuration: Configuration = Configuration())
-
-    // Browser stores
-    public func stores(for browser: Browser) -> [BrowserCookieStore]
-    public func stores(in browsers: [Browser]) -> [BrowserCookieStore]
-
-    // Query cookies
-    public func records(matching query: BrowserCookieQuery, in store: BrowserCookieStore) throws -> [BrowserCookieRecord]
-    public func records(matching query: BrowserCookieQuery, in browser: Browser) throws -> [BrowserCookieStoreRecords]
-    public func records(matching query: BrowserCookieQuery, in browsers: [Browser]) throws -> [BrowserCookieStoreRecords]
-
-    public func cookies(matching query: BrowserCookieQuery, in store: BrowserCookieStore) throws -> [HTTPCookie]
-    public func cookies(matching query: BrowserCookieQuery, in browser: Browser) throws -> [HTTPCookie]
-    public func cookies(matching query: BrowserCookieQuery, in browsers: [Browser]) throws -> [HTTPCookie]
-}
-```
-
-### Configuration
-
-```swift
-public struct BrowserCookieClient.Configuration {
-    public var homeDirectories: [URL]
-    public var decryptionFailurePolicy: BrowserCookieDecryptionFailurePolicy
-}
-
-public enum BrowserCookieDecryptionFailurePolicy {
-    case bestEffort
-    case strict
-}
-```
-
-### BrowserCookieQuery
-
-```swift
-public struct BrowserCookieQuery {
-    public var domains: [String]
-    public var domainMatch: BrowserCookieDomainMatch
-    public var domainPattern: String?
-    public var pathPattern: String?
-    public var useRegex: Bool
-    public var paths: [String]
-    public var pathMatch: BrowserCookiePathMatch
-    public var secureOnly: Bool?
-    public var httpOnlyOnly: Bool?
-    public var excludeSession: Bool
-    public var minExpiryDate: Date?
-    public var maxExpiryDate: Date?
-    public var sameSite: BrowserCookieSameSite?
-    public var origin: BrowserCookieOriginStrategy
-    public var includeExpired: Bool
-    public var referenceDate: Date
-}
-```
-
-### BrowserCookieRecord
-
-```swift
-public struct BrowserCookieRecord {
-    public var domain: String
-    public var name: String
-    public var path: String
-    public var value: String
-    public var expires: Date?
-    public var createdAt: Date?
-    public var lastAccessedAt: Date?
-    public var isSecure: Bool
-    public var isHTTPOnly: Bool
-    public var sameSite: BrowserCookieSameSite?
-    public var priority: BrowserCookiePriority?
-    public var partitionKey: String?
-    public var isSameParty: Bool?
-    public var redactedValue: String
-    public func redactedValue(prefix: Int, suffix: Int) -> String
-}
-```
-
-Note: optional fields (e.g. `createdAt`, `priority`, `partitionKey`) depend on browser support and storage format.
-
-### Field Availability (By Browser)
-
-| Field | Chromium | Firefox | Safari/WebKit |
-|------|----------|---------|---------------|
-| `domain`, `name`, `path`, `value` | ✓ | ✓ | ✓ |
-| `expires` | ✓ | ✓ | ✓ |
-| `createdAt` | ✓ | ✓ | ✓ |
-| `lastAccessedAt` | ✓ | ✓ | - |
-| `priority` | ✓ | ✓ | - |
-| `partitionKey` | ✓ | ✓ | - |
-| `isSameParty` | ✓ | ✓ | - |
-| `sameSite` | ✓ | ✓ | - |
-
-### BrowserCookieExport
-
-```swift
-public struct BrowserCookieExport {
-    public var schemaVersion: Int
-    public var generatedAt: Date
-    public var stores: [BrowserCookieStoreExport]
-    public func jsonData(prettyPrinted: Bool = true) throws -> Data
-}
-
-public struct BrowserCookieStoreExport {
-    public var browser: Browser
-    public var profileId: String
-    public var profileName: String
-    public var kind: BrowserCookieStoreKind
-    public var label: String
-    public var records: [BrowserCookieExportRecord]
-}
-```
-
-## See Also
-
-[Helix](https://github.com/sriinnu/Helix) – Command-line parsing framework
-
-## 📄 License
-
-MIT License - Copyright (c) 2026 Srinivas Pendela
-
----
-
-**GitHub:** https://github.com/sriinnu/Silo  
-**Author:** Srinivas Pendela (hello@srinivas.dev)

package/Packages/Silo/Sources/Silo/BinaryCookiesReader.swift

@@ -1,169 +0,0 @@
-import Foundation
-
-/// Parser for Safari/WebKit Cookies.binarycookies files (macOS and iOS).
-struct BinaryCookiesReader {
-    func readCookies(from url: URL) throws -> [BrowserCookieRecord] {
-        let data = try Data(contentsOf: url)
-        return try parse(data: data)
-    }
-
-    func parse(data: Data) throws -> [BrowserCookieRecord] {
-        guard readTag(in: data, at: 0) == "cook" else {
-            throw BrowserCookieError.loadFailed(
-                browser: .safari,
-                details: "Invalid cookie file header.")
-        }
-
-        guard let pageCount = readUInt32BE(in: data, at: 4) else {
-            return []
-        }
-
-        var pageSizes: [Int] = []
-        var offset = 8
-        for _ in 0..<pageCount {
-            guard let size = readUInt32BE(in: data, at: offset) else { break }
-            pageSizes.append(Int(size))
-            offset += 4
-        }
-
-        var records: [BrowserCookieRecord] = []
-        for size in pageSizes {
-            guard offset + size <= data.count else { break }
-            let pageData = data.subdata(in: offset..<(offset + size))
-            records.append(contentsOf: parsePage(pageData))
-            offset += size
-        }
-        return records
-    }
-
-    private func parsePage(_ pageData: Data) -> [BrowserCookieRecord] {
-        guard pageData.count >= 8 else { return [] }
-        let pageTag = readTag(in: pageData, at: 0)
-        let pageHeaderBE = readUInt32BE(in: pageData, at: 0)
-        let pageHeaderLE = readUInt32LE(in: pageData, at: 0)
-        guard pageTag == "page" || pageHeaderBE == 0x00000100 || pageHeaderLE == 0x00000100 else { return [] }
-        guard let cookieCount = readUInt32LE(in: pageData, at: 4) else { return [] }
-
-        var offsets: [Int] = []
-        var offset = 8
-        for _ in 0..<cookieCount {
-            guard let cookieOffset = readUInt32LE(in: pageData, at: offset) else { break }
-            offsets.append(Int(cookieOffset))
-            offset += 4
-        }
-
-        var records: [BrowserCookieRecord] = []
-        for cookieOffset in offsets {
-            if let record = parseCookie(in: pageData, at: cookieOffset) {
-                records.append(record)
-            }
-        }
-        return records
-    }
-
-    private func parseCookie(in pageData: Data, at offset: Int) -> BrowserCookieRecord? {
-        guard let sizeValue = readUInt32LE(in: pageData, at: offset) else { return nil }
-        let size = Int(sizeValue)
-        guard size > 0, offset + size <= pageData.count else { return nil }
-
-        guard size >= Self.cookieHeaderSize else { return nil }
-
-        let flags = readUInt32LE(in: pageData, at: offset + 8) ?? 0
-        guard let domainOffset = readUInt32LE(in: pageData, at: offset + 16),
-              let nameOffset = readUInt32LE(in: pageData, at: offset + 20),
-              let pathOffset = readUInt32LE(in: pageData, at: offset + 24),
-              let valueOffset = readUInt32LE(in: pageData, at: offset + 28) else {
-            return nil
-        }
-
-        let recordBase = offset
-        let recordLimit = offset + size
-        let expiryOffset = recordBase + 40
-        let creationOffset = recordBase + 48
-        var expirySeconds = readDoubleLE(in: pageData, at: expiryOffset)
-        var creationSeconds = readDoubleLE(in: pageData, at: creationOffset)
-        if expirySeconds == nil {
-            let fallbackExpiry = recordBase + size - 16
-            expirySeconds = readDoubleLE(in: pageData, at: fallbackExpiry)
-            if creationSeconds == nil {
-                creationSeconds = readDoubleLE(in: pageData, at: fallbackExpiry + 8)
-            }
-        }
-        guard let expirySeconds else { return nil }
-
-        guard let domain = readCString(in: pageData, at: recordBase + Int(domainOffset), limit: recordLimit),
-              let name = readCString(in: pageData, at: recordBase + Int(nameOffset), limit: recordLimit),
-              let path = readCString(in: pageData, at: recordBase + Int(pathOffset), limit: recordLimit),
-              let value = readCString(in: pageData, at: recordBase + Int(valueOffset), limit: recordLimit) else {
-            return nil
-        }
-
-        let expires = expirySeconds > 0 ? Date(timeIntervalSinceReferenceDate: expirySeconds) : nil
-        let createdAt = creationSeconds.flatMap { $0 > 0 ? Date(timeIntervalSinceReferenceDate: $0) : nil }
-        let isSecure = (flags & 0x1) != 0
-        let isHTTPOnly = (flags & 0x4) != 0
-
-        return BrowserCookieRecord(
-            domain: domain,
-            name: name,
-            path: path.isEmpty ? "/" : path,
-            value: value,
-            expires: expires,
-            createdAt: createdAt,
-            isSecure: isSecure,
-            isHTTPOnly: isHTTPOnly,
-            sameSite: nil)
-    }
-
-    private func readTag(in data: Data, at offset: Int) -> String? {
-        guard offset + 4 <= data.count else { return nil }
-        let slice = data[offset..<(offset + 4)]
-        return String(data: slice, encoding: .ascii)
-    }
-
-    private func readCString(in data: Data, at offset: Int, limit: Int? = nil) -> String? {
-        guard offset < data.count else { return nil }
-        let cappedLimit = min(limit ?? data.count, data.count)
-        guard offset < cappedLimit else { return nil }
-        var end = offset
-        while end < cappedLimit && data[end] != 0 {
-            end += 1
-        }
-        let slice = data[offset..<end]
-        return String(data: slice, encoding: .utf8)
-    }
-
-    private func readUInt32BE(in data: Data, at offset: Int) -> UInt32? {
-        guard offset + 4 <= data.count else { return nil }
-        let b0 = UInt32(data[offset]) << 24
-        let b1 = UInt32(data[offset + 1]) << 16
-        let b2 = UInt32(data[offset + 2]) << 8
-        let b3 = UInt32(data[offset + 3])
-        return b0 | b1 | b2 | b3
-    }
-
-    private func readUInt32LE(in data: Data, at offset: Int) -> UInt32? {
-        guard offset + 4 <= data.count else { return nil }
-        let b0 = UInt32(data[offset])
-        let b1 = UInt32(data[offset + 1]) << 8
-        let b2 = UInt32(data[offset + 2]) << 16
-        let b3 = UInt32(data[offset + 3]) << 24
-        return b0 | b1 | b2 | b3
-    }
-
-    private func readUInt64LE(in data: Data, at offset: Int) -> UInt64? {
-        guard offset + 8 <= data.count else { return nil }
-        var value: UInt64 = 0
-        for index in 0..<8 {
-            value |= UInt64(data[offset + index]) << (8 * index)
-        }
-        return value
-    }
-
-    private func readDoubleLE(in data: Data, at offset: Int) -> Double? {
-        guard let bits = readUInt64LE(in: data, at: offset) else { return nil }
-        return Double(bitPattern: bits)
-    }
-
-    private static let cookieHeaderSize = 56
-}