feat: add the authenticated runtime seam

[altaywtf]

Part of #123
Refs #130
Preserves #129

Summary

• Add one PutioRuntime that privately owns the shared authenticated PutioSDK used by session and file operations.
• Convert mutable SDK responses into immutable, Sendable account and file snapshots; expose root and nested first-page listing without credentials, cursors, or token-bearing URLs.
• Preserve cancellation, classify runtime failures, expire the whole session on 401/403, and reject responses from superseded authentication generations.
• Compose the iOS shell around the runtime so the browser layer can consume the seam next.

This gives the rollout one safe authenticated boundary before file-browser UI and playback land.

Reviewer Guide

• Highest-risk area: authentication-generation checks across restore, sign-out, a fresh sign-in, duplicate sign-in attempts, and in-flight file requests.
• Start with PutioRuntime.swift, then PutioSessionStore.swift and the gated race tests in PutioRuntimeTests.swift.

Visual Aids

• Recording: seeded signed-in shell → local and remote sign-out → signed-out recovery

Validation

• mise run verify
• Affected iOS shell exercised with the deterministic signed-in recording scenario
• Proof captured with mise run harness -- record --platform ios --scenario signed-in --record-seconds 7
• Proof published separately with the repository harness
• Additional targeted checks:
  • 23 focused runtime/session tests pass.
  • The recording manifest pins ffb51a7650ec7071e1c3d3a6bd7ff3e1fa5800c5; app stdout/stderr are empty.
  • Codex-high Slopguard reviewed the complete 90959c0...ffb51a7 branch diff and returned clean with 0 findings.

Sanity Checks

• Signed-out listing issues no HTTP request.
• Cancellation retains the signed-in session and persisted token.
• 401/403 clear credentials and expire the shared session.
• Old-session success and auth-failure responses cannot affect a fresh session.
• Sign-in is blocked while remote logout is pending; a late restore cannot erase an in-flight sign-in.
• A duplicate sign-in attempt cannot clear the first OAuth transaction or reject its valid callback.

Benchmarks

N/A — this layer adds runtime contracts, not a performance-sensitive UI path.

Notes

• iOS files: folder browsing, sorting, and search #130 remains open: file-browser UI, navigation, and restoration remain in the next layer.
• Pagination continuation remains blocked on Add cursor continuation for files listing putio-sdk-swift#38.
• Playback and iOS video playback with resume, next-video, and the conversion gate #132 remain downstream of Add playback-source, device-code polling, and typed-settings helpers putio-sdk-swift#40; this PR does not expose raw tokens or construct playback URLs.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-08-30T08:25:25.422260Z	c5b7f4e	New commits

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[Copilot]

🟢 Approval recommended

The session-generation gating, session-expiry behavior, and runtime snapshot/redaction goals are covered by focused tests and the integration updates are consistent with the new runtime seam.

Pull request overview

This PR introduces an authenticated runtime seam (PutioRuntime) that owns the shared authenticated PutioSDK, while converting SDK models into immutable, Sendable snapshots and hardening session correctness via authentication-generation gating and 401/403 session expiry. It composes the iOS shell around the runtime so downstream browser/playback layers can depend on a safe authenticated boundary.

Changes:

• Added PutioRuntime + runtime snapshot models (PutioAccountSnapshot, PutioFileItem, etc.) and mapped first-page root/nested listings without exposing token-bearing URLs.
• Updated PutioSessionStore to gate restore/sign-in/sign-out via an authenticationGeneration, add .signingOut, and expire the session on auth rejection.
• Added targeted runtime/session race tests (including gated URLProtocol fixtures) and wired the iOS shell + harness factory to construct and use PutioRuntime.

File summaries

File	Description
Packages/PutioCore/Tests/PutioCoreTests/PutioSessionStoreTests.swift	Updates assertions for the new account snapshot and adds coverage for restore vs. in-flight sign-in ordering.
Packages/PutioCore/Tests/PutioCoreTests/PutioRuntimeTests.swift	Adds comprehensive tests for request sharing, snapshot redaction, error classification, cancellation, and auth-generation races.
Packages/PutioCore/Sources/PutioCore/Session/PutioSessionStore.swift	Introduces authentication-generation gating, .signingOut, session expiry behavior, and snapshotting of account info.
Packages/PutioCore/Sources/PutioCore/Runtime/PutioRuntimeModels.swift	Adds immutable Sendable runtime-facing models for accounts, files, folder contents, and runtime errors.
Packages/PutioCore/Sources/PutioCore/Runtime/PutioRuntime.swift	Implements the authenticated runtime boundary, list operation, cancellation behavior, and SDK error classification + session expiry.
Apps/Shared/Sources/PutioRuntimeFactory.swift	Switches harness/runtime construction from a raw session store to the new PutioRuntime.
Apps/iOS/Sources/PutioApp.swift	Composes the iOS shell around PutioRuntime and updates UI plumbing to use session state + account snapshot.

Review details

• Files reviewed: 7/7 changed files
• Comments generated: 0
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1b7375a528

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[altaywtf]

Second-pass review follow-up; fixes pushed to the branch.

Fixed in c5b7f4e — completeSignIn's guard-fail path advanced the authentication generation and forced .signedOut from any state. A stray callback while .signedIn kicked a valid session to the sign-in screen with the keychain token left behind, so the next restore() silently signed back in; during .signingOut the advanced generation made the post-logout guard bail, so neither path cleared the SDK token. The path now early-returns outside .authenticating. Covered by testStrayCallbackWhileSignedInIsIgnored, testStrayCallbackAfterCancelIsIgnored, and the gated testStrayCallbackDuringSignOutDoesNotBlockCredentialCleanup.

Flagged upstream in putdotio/putio-sdk-swift#52 — the session store mutates PutioSDK.config on the main actor while the SDK's @concurrent request path reads it on the global executor, unchecked under Swift 5 mode. Latent until concurrent data-plane callers exist; the fix belongs in the SDK.

Recorded as intentional — PutioRuntime classifies cancellation before auth failure, so a real 401 racing task cancellation leaves the session .signedIn until the next request's 401. Cancelled work must not mutate state; the miss self-heals.

Verified: 42 PutioCore tests on c5b7f4e; full mise run verify at stack top f82b0e5.