Add OpenSpec change for Windows managed local admin account (#43488) by getvictor · Pull Request #48725 · fleetdm/fleet

getvictor · 2026-07-04T08:48:31Z

Related issue: #43488 (planning artifacts only, does not resolve the story)

Checklist for submitter

If some of the following don't apply, delete the relevant line.

Changes file added for user-visible changes in changes/, orbit/changes/ or ee/fleetd-chrome/changes.
See Changes files for more information. (Not applicable: OpenSpec planning documents only, no user-visible change.)

Details

Adds the OpenSpec change openspec/changes/windows-local-admin-account/ for the "Windows: Create a local admin account" story (#43488):

proposal.md: why and what, with three new capabilities declared
design.md: key decisions with alternatives (fleetd over Accounts CSP, device-side password generation with escrow-up, table reuse, deprecated fields as aliases), risks, migration plan
specs/: requirement/scenario specs for managed-local-account-config, windows-managed-local-account-provisioning, and windows-managed-account-password-access
tasks.md: implementation checklist mapped to sub-issues Windows local admin account: managed_local_account_settings config surface and GitOps #48720 to Windows local admin account: documentation and engineering QA #48724
engineering-spec.md: the full engineering spec with verified code anchors (copied into the change directory because ai/ is gitignored)

No code changes. Implementation lands through the sub-issues.

https://claude.ai/code/session_019zNzvuWwhFMiwBKojUnfdH

Summary by CodeRabbit

Chores
- Added or updated project metadata for a Windows local admin account change entry.
- Included spec-driven schema information and a creation date for better tracking.

Proposal, design, capability specs, tasks, and the verified engineering spec for creating a hidden _fleetadmin break-glass admin on Windows hosts during OOBE enrollment (fleetd-created, password escrowed to Fleet). Sub-issues #48720-#48724. Claude-Session: https://claude.ai/code/session_019zNzvuWwhFMiwBKojUnfdH

claude

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review to trigger a review and subscribe this PR to future pushes, or @claude review once for a one-time review.

_{Tip: disable this comment in your organization's Code Review settings.}

getvictor · 2026-07-04T08:48:40Z

@coderabbitai review

getvictor · 2026-07-04T08:48:41Z

/review

coderabbitai · 2026-07-04T08:48:46Z

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

coderabbitai · 2026-07-04T08:50:19Z

Walkthrough

This change adds a new .openspec.yaml metadata file under the windows-local-admin-account openspec change directory, specifying a schema field set to spec-driven and a created date of 2026-07-04. No code entities or public interfaces are altered.

Changes

Cohort / File	Summary
openspec/changes/windows-local-admin-account/.openspec.yaml	Added metadata fields `schema: spec-driven` and `created: 2026-07-04`

Sequence Diagram(s)

No sequence diagram applicable; this change consists solely of metadata addition.

Possibly related issues

Windows local admin account: documentation and engineering QA #48724: Part of the same windows-local-admin-account feature/spec work this metadata file supports.
Windows local admin account: fleetd creates and hides the account on Windows #48723: Corresponds to the same Windows local admin account feature this spec metadata file is scaffolding for.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title accurately summarizes the PR as an OpenSpec change for the Windows local admin account story.
Description check	✅ Passed	The description matches the template well and includes the related issue, checklist context, and implementation details.

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch victor-openspec-windows-local-admin-43488

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

Copilot

Pull request overview

Adds an OpenSpec planning change set for the “Windows: Create a local admin account” story (#43488), capturing the proposal, design decisions, requirements/scenarios, and an implementation task checklist (no production code changes).

Changes:

Introduces a new OpenSpec change directory under openspec/changes/windows-local-admin-account/ with proposal/design/specs/tasks.
Documents three capability specs covering config/GitOps, Windows provisioning + escrow, and password access constraints.
Adds a detailed engineering spec (with anchors, QA scenarios, and sub-issue breakdown) to guide implementation work in follow-on PRs.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
openspec/changes/windows-local-admin-account/.openspec.yaml	OpenSpec change metadata (schema + created date).
openspec/changes/windows-local-admin-account/design.md	Design decisions, goals/non-goals, risks, and migration plan for the Windows managed local admin account feature.
openspec/changes/windows-local-admin-account/engineering-spec.md	Detailed end-to-end engineering spec including flow diagram, API notes, and implementation guidance.
openspec/changes/windows-local-admin-account/proposal.md	High-level “why/what/impact” proposal for the feature and its capabilities.
openspec/changes/windows-local-admin-account/specs/managed-local-account-config/spec.md	Requirements/spec for per-platform managed local account enablement, aliasing, premium gating, and GitOps round-trip.
openspec/changes/windows-local-admin-account/specs/windows-managed-account-password-access/spec.md	Requirements/spec for Windows password retrieval, rotation constraints, and UI surfacing.
openspec/changes/windows-local-admin-account/specs/windows-managed-local-account-provisioning/spec.md	Requirements/spec for orbit notification gating, device-side account creation, escrow, crash-safety, and version skew behavior.
openspec/changes/windows-local-admin-account/tasks.md	Implementation checklist mapped to sub-issues #48720–#48724.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+#### Scenario: Legacy write reflects on the new surface
+- **WHEN** a client sets `setup_experience.enable_managed_local_account: true` via `PATCH /setup_experience`
+- **THEN** `GET /config` returns `true` for both `setup_experience.enable_managed_local_account` and `apple_settings.managed_local_account_settings.enabled`
+


+### Requirement: Rotation unavailable for Windows
+`POST /api/v1/fleet/hosts/{id}/managed_account_password/rotate` SHALL reject Windows hosts with an error stating rotation is not available for Windows (rotation ships in #43489), and the rotation cron MUST never select Windows-shaped rows (NULL `command_uuid`, NULL `account_uuid`).
+


qodo-free-for-open-source-projects · 2026-07-04T08:52:22Z

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. ~~Wrong JSON field path~~ ✓ Resolved 🐞 Bug ≡ Correctness

Description

The new OpenSpec artifacts specify the Host details response uses mdm.managed_local_account, but
the current backend/frontend model nests this under mdm.os_settings.managed_local_account. If
implemented as written, backend/frontend changes would target a non-existent field and the UI/data
contract would diverge from the actual host schema.

Code

openspec/changes/windows-local-admin-account/specs/windows-managed-account-password-access/spec.md[R25-30]

+### Requirement: Host details surface
+The host detail API response SHALL include `mdm.managed_local_account` (status, password availability) for Windows hosts when Windows MDM is enabled, and the Host details UI SHALL show the "Show managed account" action for Windows hosts with a managed account row, opening the existing modal without rotation controls.
+
+#### Scenario: Host detail response populated
+- **WHEN** a Windows host with an escrowed row is fetched via the host detail API
+- **THEN** the response includes `mdm.managed_local_account` with `status: "verified"` and `password_available: true`

Evidence
The host API/schema nests OS-level settings under mdm.os_settings (not directly under mdm), and
the managed local account status is defined within those OS settings. Frontend types mirror the same
nesting, so the OpenSpec path is inconsistent with the current codebase contract.
server/fleet/hosts.go[627-632]
server/fleet/hosts.go[678-682]
frontend/interfaces/host.ts[122-137]
frontend/interfaces/host.ts[162-177]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The OpenSpec docs/specs currently refer to `mdm.managed_local_account` (and in one place `host.mdm.managed_local_account`), but the Host JSON schema actually places `managed_local_account` under `mdm.os_settings`.
### Issue Context
Backend host serialization uses `json:"os_settings"` for OS settings, and `managed_local_account` is a field on `HostMDMOSSettings`. Frontend types also model `managed_local_account` under `mdm.os_settings`.
### Fix Focus Areas
- openspec/changes/windows-local-admin-account/specs/windows-managed-account-password-access/spec.md[25-30]
- openspec/changes/windows-local-admin-account/engineering-spec.md[386-419]
### Expected change
- Replace `mdm.managed_local_account` with `mdm.os_settings.managed_local_account`.
- Replace `host.mdm.managed_local_account` with `host.mdm.os_settings.managed_local_account`.
- (Optional) Add a one-line note that this is surfaced under `os_settings` for all platforms to prevent future confusion.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Escrow endpoint no longer rejects when the team setting was toggled off after the notification (prevents orphaning a created account with an unrecoverable password), verifies Windows eligibility via the MDM enrollment instead of host.Platform alone (empty during early OOBE), and the illustrative migration SQL matches the existing column charset. Claude-Session: https://claude.ai/code/session_019zNzvuWwhFMiwBKojUnfdH

Correct the host detail JSON path to mdm.os_settings.managed_local_account (managed_local_account lives on HostMDMOSSettings, not directly under mdm), harmonize the Windows-shaped row definition used by the rotation cron scenarios, and use full API paths consistently. Claude-Session: https://claude.ai/code/session_019zNzvuWwhFMiwBKojUnfdH

getvictor requested a review from lukeheath as a code owner July 4, 2026 08:48

Copilot AI review requested due to automatic review settings July 4, 2026 08:48

claude Bot reviewed Jul 4, 2026

View reviewed changes

getvictor temporarily deployed to Docker Hub July 4, 2026 08:48 — with GitHub Actions Inactive

Copilot started reviewing on behalf of getvictor July 4, 2026 08:48 View session

Copilot AI reviewed Jul 4, 2026

View reviewed changes

qodo-free-for-open-source-projects Bot reviewed Jul 4, 2026

View reviewed changes

Comment thread ...ec/changes/windows-local-admin-account/specs/windows-managed-account-password-access/spec.md Outdated

getvictor mentioned this pull request Jul 4, 2026

Windows local admin account: orbit notification, password escrow, and host endpoints #48721

Open

10 tasks

getvictor had a problem deploying to Docker Hub July 4, 2026 09:09 — with GitHub Actions Error

getvictor temporarily deployed to Docker Hub July 4, 2026 09:15 — with GitHub Actions Inactive

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add OpenSpec change for Windows managed local admin account (#43488)#48725

Add OpenSpec change for Windows managed local admin account (#43488)#48725
getvictor wants to merge 3 commits into
mainfrom
victor-openspec-windows-local-admin-43488

getvictor commented Jul 4, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

claude Bot left a comment

Uh oh!

getvictor commented Jul 4, 2026

Uh oh!

getvictor commented Jul 4, 2026

Uh oh!

coderabbitai Bot commented Jul 4, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Jul 4, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

qodo-free-for-open-source-projects Bot commented Jul 4, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		### Requirement: Rotation unavailable for Windows
		`POST /api/v1/fleet/hosts/{id}/managed_account_password/rotate` SHALL reject Windows hosts with an error stating rotation is not available for Windows (rotation ships in #43489), and the rotation cron MUST never select Windows-shaped rows (NULL `command_uuid`, NULL `account_uuid`).

Uh oh!

Conversation

getvictor commented Jul 4, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Checklist for submitter

Details

Summary by CodeRabbit

Uh oh!

claude Bot left a comment

Choose a reason for hiding this comment

Claude Code Review

Uh oh!

getvictor commented Jul 4, 2026

Uh oh!

getvictor commented Jul 4, 2026

Uh oh!

coderabbitai Bot commented Jul 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot commented Jul 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Sequence Diagram(s)

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

qodo-free-for-open-source-projects Bot commented Jul 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code Review by Qodo

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

getvictor commented Jul 4, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jul 4, 2026 •

edited

Loading

coderabbitai Bot commented Jul 4, 2026 •

edited

Loading

qodo-free-for-open-source-projects Bot commented Jul 4, 2026 •

edited

Loading