Add DeviceCheck App Attest workflow

ROADMAP.md

@@ -328,6 +328,7 @@ In Progress
 - [ ] Add a dedicated Xcode 27 beta LLDB MCP workflow skill after `xcrun lldb-mcp` startup is validated. Xcode 27 Beta 2 exposes `lldb-mcp`, and Apple Dev Skills now carries an experimental `xcode_lldb` MCP config entry, but local `--help` invocation failed on 2026-06-26 with a missing `lib_CompilerSwiftIDEUtils.dylib` rpath load.
 - [ ] Add `apple-dev-skills:xcode-agent-plugin-workflow` now that the live Xcode 27 beta plug-in import paths are verified through installed Codex state, local folder import, and public Git URL import.
 - [x] Refresh `xcode-build-run-workflow` and `xcode-testing-workflow` so setup and permissions route to the new coding-intelligence skill while build/test execution stays owned by the existing skills.
+- [x] Document Xcode command-line toolchain selection for stable and beta Xcode installs, including command-scoped `DEVELOPER_DIR`, explicit global `xcode-select --switch`, restore steps, and current system-wide beta app paths.
 - [ ] Refresh SwiftUI guidance for Xcode 27 APIs such as `ContentBuilder`, `@State` macro behavior, reorderable containers, generalized swipe actions, toolbar overflow, URL-backed documents, AsyncImage request/session APIs, and gesture input kinds.
 - [ ] Refresh AppKit, UIKit, and Icon Composer guidance for the Xcode 27 beta changes recorded in the plan.
 
@@ -501,7 +502,7 @@ Planned
 - [ ] Add common skill constraint checks for Codex and OpenCode first, then include Zed as an informational follow-up target.
 - [ ] Add a dry-run OpenCode skills export plan for `.agents/skills` and `.opencode/skills`, starting with project-local fixtures and temporary homes.
 - [ ] Evaluate OpenCode adapters for `.opencode/skills`, `opencode.json`, MCP config, permissions, and TypeScript plugin modules.
-- [ ] Evaluate Xcode 27 beta adapters using `DEVELOPER_DIR=/Users/galew/Applications/Betas/Xcode-beta.app/Contents/Developer`, including Xcode-launched Codex configuration, MCP bridge behavior, and Xcode plug-in imports through the official Settings UI. Initial live beta bridge and plug-in import evidence was captured on 2026-06-23.
+- [ ] Evaluate Xcode 27 beta adapters using command-scoped `DEVELOPER_DIR` for the intended system-wide beta app, including Xcode-launched Codex configuration, MCP bridge behavior, and Xcode plug-in imports through the official Settings UI. Initial live beta bridge and plug-in import evidence was captured on 2026-06-23.
 - [ ] Add a Socket-to-Xcode install support assessment that classifies each child plugin across Xcode-launched Codex, Xcode internal plug-ins, and external agents using Xcode MCP.
 - [ ] Add disposable Xcode import fixture generation for skill-only, skill-plus-MCP, and hook-recognition probes.
 - [ ] Capture a public Socket Git URL import matrix from Xcode Beta before claiming user-facing Xcode install support.

docs/maintainers/agent-portability-options.md

@@ -22,10 +22,10 @@ Start with Xcode 27 beta and OpenCode.
 
 Those are the two locally installed targets available for immediate smoke tests on Gale's machine:
 
-- Xcode 27 beta: `/Users/galew/Applications/Betas/Xcode-beta.app`, verified with `DEVELOPER_DIR=/Users/galew/Applications/Betas/Xcode-beta.app/Contents/Developer xcodebuild -version` as Xcode 27.0 build 27A5194q.
+- Xcode 27 beta: `/Applications/Xcode-beta.app`, verified on 2026-07-02 with `DEVELOPER_DIR=/Applications/Xcode-beta.app/Contents/Developer xcodebuild -version` as Xcode 27.0 build 27A5209h.
 - Xcode 27 beta live bridge: verified on 2026-06-23 with the beta app open and selected through `MCP_XCODE_PID`; `run-agent --dry-run codex` resolved the beta-scoped Codex runtime and Xcode-specific `CODEX_HOME`. A direct `codex skills export` attempt through that runtime failed in this beta with `unrecognized subcommand 'export'`, so do not rely on that as an install or export path.
 - Xcode 27 beta plug-in import: verified on 2026-06-23 through the Xcode Beta Settings UI. `Import from Codex`, `Add from file`, and `Add from URL` all recognized agentic plug-in payloads; `Add from URL` accepted `https://github.com/gaelic-ghost/socket.git` and enumerated Socket child plug-ins before import.
-- Active command-line Xcode: `/Applications/Xcode.app`, currently Xcode 26.5 build 17F42 through the default `xcodebuild -version`.
+- Active command-line Xcode: `/Applications/Xcode-beta.app/Contents/Developer`, currently Xcode 27.0 build 27A5209h through the default `xcodebuild -version`.
 - OpenCode CLI: `/opt/homebrew/bin/opencode`, verified as 1.17.9.
 - OpenCode Desktop: `/Applications/OpenCode.app`, present locally.
 
@@ -63,10 +63,10 @@ Xcode support needs three different answers:
 
 Local validation target:
 
-- Use `DEVELOPER_DIR=/Users/galew/Applications/Betas/Xcode-beta.app/Contents/Developer` for Xcode 27 beta checks until the active command-line developer directory is intentionally changed.
-- Open `/Users/galew/Applications/Betas/Xcode-beta.app` for live beta UI, MCP, agent, and plug-in checks instead of treating a closed app as a blocker.
+- Prefer command-scoped `DEVELOPER_DIR` for Xcode beta checks when the task should not change the global command-line developer directory. Current system-wide beta candidates are `/Applications/Xcode-beta.app` and `/Applications/Betas/Xcode-beta.app`.
+- Open the intended stable or beta Xcode app for live UI, MCP, agent, and plug-in checks instead of treating a closed app as a blocker.
 - Use `MCP_XCODE_PID` when stable and beta Xcode processes could both exist or when the bridge must target the beta process explicitly.
-- Keep the default Xcode 26.5 path untouched unless a task explicitly needs `xcode-select` changes.
+- Change global `xcode-select` only when the task explicitly needs the default command-line tools selection to change. Record the previous `xcode-select -p` value, switch with `sudo xcode-select --switch <Xcode.app/Contents/Developer>`, verify, and restore the previous path when the global check is finished.
 
 Practical Socket implication:
 

docs/maintainers/devicecheck-app-attest-skill-plan.md

@@ -0,0 +1,92 @@
+# DeviceCheck and App Attest Skill Record
+
+This record captures the shipped Apple Dev Skills expansion for the DeviceCheck framework, including per-device DeviceCheck state and App Attest app-instance validation.
+
+## Status
+
+Implemented. The first implementation shipped one focused workflow skill, `devicecheck-app-attest-workflow`, rather than separate `device-identification` and `app-attest` skills.
+
+## Ownership
+
+This skill belongs in `plugins/apple-dev-skills` because it depends on Apple framework behavior, app IDs, entitlements, Xcode signing state, Apple Developer account setup, local Apple documentation, and Apple server APIs.
+
+The skill should stay separate from the broader client auth and sync milestone. DeviceCheck and App Attest are risk and integrity signals for a server-backed app, not a general credential-storage or session-management workflow.
+
+The server verification side should be explicit but bounded. Apple Dev Skills can guide the client/server contract, challenge shape, App Attest object flow, and validation checklist, but server implementation should hand off to server-side Swift, OpenAPI, or RPC workflows when the backend code or API contract is the primary change.
+
+## Documented Apple Behavior To Rely On
+
+Apple documentation describes DeviceCheck as a framework plus Apple server APIs for reducing fraudulent use by managing device state and asserting app integrity.
+
+Device identification uses `DCDevice` in the app to generate an ephemeral token. The server uses that token with a JWT-backed Apple server request to query, update, or validate two per-device bits stored by Apple. The app must check `DCDevice.current.isSupported`, and the app must have an Apple Developer registered App ID.
+
+App Attest uses `DCAppAttestService` to generate a Secure Enclave-backed key, ask Apple to attest that key, and later generate assertions for sensitive server requests. The app must check `DCAppAttestService.shared.isSupported`, the app must have a registered App ID, and server-side challenge handling is required to prevent replay attacks.
+
+App Attest has important rollout and environment constraints:
+
+- Sandbox and production keys and receipts are separate.
+- Distributed apps operate in production mode.
+- Large existing user bases should ramp attestation gradually because attestation contacts Apple servers and can be rate limited.
+- Attestation failures with `serverUnavailable` should retry later using the same key and `clientDataHash`.
+- App Attest does not prove that a device operating system is uncompromised; it supplies one signal for a broader fraud-risk decision.
+- On macOS, App Attest verification has macOS-specific signing identifier and key access-policy checks.
+
+## Implemented Skill
+
+### `devicecheck-app-attest-workflow`
+
+Use for DeviceCheck and App Attest decisions in Apple-platform apps, including `DCDevice`, per-device two-bit state, `DCAppAttestService`, App Attest key lifecycle, server challenge design, attestation and assertion request shapes, app IDs, entitlements, sandbox versus production environments, rollout/rate-limit planning, and client/server handoffs.
+
+This skill helps an agent:
+
+- classify whether the request is DeviceCheck two-bit device state, App Attest app-instance integrity, or a broader auth/session/sync concern
+- apply the Apple docs gate before making current framework, entitlement, platform, or server-endpoint claims
+- preserve the client/server boundary instead of pretending the app can validate itself
+- keep key identifiers persistent but avoid storing secrets or treating attestation objects as app-side proof
+- distinguish development, sandbox, TestFlight, App Store, Enterprise, Developer ID, and macOS signing behavior where Apple docs require it
+- plan server challenges, replay protection, assertion counters, public-key storage, receipt storage, and risk metrics without making Apple Dev Skills own a backend implementation
+- route Xcode signing, entitlements, App ID capability, build, run, simulator, device, and test follow-through to `xcode-build-run-workflow` or `xcode-testing-workflow`
+- route generated client APIs to `swift-openapi-client-workflow`
+- route backend validation implementation to the relevant server-side Swift or API-contract workflow when available
+
+## Shipped Skill Shape
+
+The shipped first version is guidance and routing, not a deterministic validator. App Attest server verification includes CBOR, COSE, ASN.1, certificate-chain, receipt, environment, signing-category, and counter checks, which are too stack-specific for a tiny first slice.
+
+Shipped first payload:
+
+- `SKILL.md` with the core workflow, docs gate, classification, handoffs, and guardrails.
+- `agents/openai.yaml` metadata generated from the skill body.
+- `references/devicecheck-device-state.md` for `DCDevice`, two-bit state, JWT, query/update/validate endpoints, privacy, and reset semantics.
+- `references/app-attest-client-flow.md` for `DCAppAttestService`, key ID persistence, challenge hashing, attestation, assertions, `DCError`, and retry behavior.
+- `references/app-attest-server-validation.md` for server-side validation checklist, receipt/risk metric handling, sandbox versus production, replay protection, counters, and macOS-specific validation notes.
+- `references/entitlements-app-id-and-validation.md` for App ID, DeviceCheck capability, App Attest environment entitlement, provisioning, Xcode handoffs, simulator/device expectations, and rollout gates.
+
+Avoid scripts in the first slice unless a concrete backend stack needs one. If a later project repeatedly needs App Attest verification in Swift, add a separate deterministic reference implementation or test helper after the server-side owner is clear.
+
+## Implementation Slices
+
+1. Planning and docs evidence:
+   - [x] Add this plan and roadmap milestone.
+   - [x] Keep the plan grounded in Xcode and Dash documentation lookups.
+   - [x] Decide the one-skill shape unless implementation evidence shows the workflow becomes too large.
+2. Skill scaffold:
+   - [x] Initialize `devicecheck-app-attest-workflow` under `plugins/apple-dev-skills/skills/`.
+   - [x] Add references and generated `agents/openai.yaml`.
+   - [x] Keep `SKILL.md` concise and move detailed validation checklists into references.
+3. Metadata and inventory:
+   - [x] Update `plugins/apple-dev-skills/.codex-plugin/plugin.json`.
+   - [x] Update `plugins/apple-dev-skills/README.md` active skill inventory and prompt list.
+   - [x] Update `plugins/apple-dev-skills/ROADMAP.md` status and ticket completion.
+4. Tests and validation:
+   - [x] Add targeted tests for frontmatter, routing boundaries, docs-gate language, server-handoff language, and metadata inventory.
+   - [x] Run `bash .github/scripts/validate_repo_docs.sh` from `plugins/apple-dev-skills`.
+   - [x] Run `uv run pytest` from `plugins/apple-dev-skills` when tests change.
+   - [x] Run `uv run scripts/validate_socket_metadata.py` from the Socket root after metadata changes.
+
+## Future Questions
+
+- The first implementation uses `devicecheck-app-attest-workflow`; a broader `apple-app-integrity-workflow` can still be considered later if another Apple integrity signal needs a shared owner.
+- Should server-validation guidance stay purely checklist-based at first, or should the initial skill include stack-specific examples for Swift server apps?
+- Should DeviceCheck two-bit state and App Attest stay permanently in one skill, or should DeviceCheck split out later if two-bit state becomes common outside App Attest integrity flows?
+- Should the first implementation include migration guidance for apps that already use custom device identifiers, receipt validation, or server-side abuse flags?

docs/maintainers/xcode-27-agentic-tooling-plan.md

@@ -43,9 +43,9 @@ Refresh checked on 2026-06-22:
 
 Live beta probe checked on 2026-06-23:
 
-- Xcode 27 beta was opened from `/Users/galew/Applications/Betas/Xcode-beta.app`.
-- `DEVELOPER_DIR=/Users/galew/Applications/Betas/Xcode-beta.app/Contents/Developer MCP_XCODE_PID=59740 xcrun mcpbridge run-agent --dry-run codex` resolved Xcode's beta-scoped Codex executable and `CODEX_HOME`.
-- `DEVELOPER_DIR=/Users/galew/Applications/Betas/Xcode-beta.app/Contents/Developer MCP_XCODE_PID=59740 xcrun mcpbridge run-agent codex skills export --output-dir /private/tmp/socket-xcode-plugin-fixture/after-file-import-skills --replace-existing` launched Xcode's beta-scoped Codex runtime, but that runtime reported `unrecognized subcommand 'export'`. Treat `skills export` as unusable from this Codex runtime until a later beta proves otherwise.
+- Xcode 27 beta was opened from the then-installed beta app path.
+- The matching beta `DEVELOPER_DIR` plus `MCP_XCODE_PID=59740 xcrun mcpbridge run-agent --dry-run codex` resolved Xcode's beta-scoped Codex executable and `CODEX_HOME`.
+- The matching beta `DEVELOPER_DIR` plus `MCP_XCODE_PID=59740 xcrun mcpbridge run-agent codex skills export --output-dir /private/tmp/socket-xcode-plugin-fixture/after-file-import-skills --replace-existing` launched Xcode's beta-scoped Codex runtime, but that runtime reported `unrecognized subcommand 'export'`. Treat `skills export` as unusable from this Codex runtime until a later beta proves otherwise.
 - Xcode Beta Settings > Intelligence > Plug-ins was inspected through the official UI. The Add Plug-in sheet exposed `Import from Claude Code`, `Import from Codex`, `Add from file`, and `Add from URL`.
 - `Import from Codex` imported the installed `apple-dev-skills` plugin as `6 Skills - Hooks`.
 - `Add from file` imported a harmless fixture folder containing `.codex-plugin/plugin.json`, `skills/<name>/SKILL.md`, and `.mcp.json` as `1 Skill - 1 MCP Server`.

docs/maintainers/xcode-plugin-install-support-plan.md

@@ -44,7 +44,7 @@ Local probe results:
 ## Non-Goals
 
 - Do not build a separate custom Xcode installer before the official UI path is exhausted.
-- Do not change `xcode-select` globally.
+- Do not change `xcode-select` globally unless the task explicitly requires a system-wide default command-line tools switch. Prefer command-scoped `DEVELOPER_DIR` for beta checks.
 - Do not rewrite Socket as an aggregate non-Codex plugin bundle.
 - Do not claim hook execution, MCP server execution, app config, or custom-agent behavior works in Xcode until runtime probes verify those surfaces.
 - Do not treat Xcode-generated files as Socket source of truth.