Skip to content

feat(app-kit): let an app's manifest mask its own credential files - #32652

Merged
bolichen97 merged 1 commit into
mainfrom
feat/app-seam-app-credential-masks
Nov 8, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
feat/app-seam-app-credential-masks

Conversation

@bolichen97

@bolichen97 bolichen97 commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A third-party app can list files under its own data directory in its manifest, and every Kiro Crew sandbox then hides them and refuses hard links on them, exactly as it hides Kiro Crew's own credential files.

Today only core can hide a file from agent sandboxes, by naming it in the sandbox leaf tables. An app that stores a provider token or a cookie under apps/<name>/data/ has no way to keep a prompt-injected agent shell from reading it, and a built-in that leaves the repository loses its rows, because core may not name an app.

Why it matters

Every app that keeps a credential on disk is readable by any sandboxed agent process unless core hard-codes the file. That blocks moving built-ins out (#26967): core can't keep naming them, and dropping the rows would expose the files. The owner approved this seam on 2026-11-07 (#26967 (comment), ruling 3): tightening only, leaves under the app's OWN data directory, nothing outside it.

Not a goal

  • Moving Ops Mission Control's provider-token store. It lives at <data home>/ops_mission_control_secrets.json, at the data-home root and outside the app's data directory, so the seam can't express it, and moving a live credential store is a data migration. Its core rows stay; see "What changed".
  • Sealing installed app trees read-only, or adding app-declared leaves to the agent tool gate or to any keystone disposition.
  • Other seams in this batch: app-registered MCP tools (app-mcp-tools), auto-approve (app-auto-approve), data outside data/ (app-data-root), stdio MCP servers (app-stdio-mcp), chat panels (app-chat-panel), agent turns and protected subdirectories such as Meetings' data/edits (app-agent-turns), public core APIs (public-core-apis) and the desktop window host (desktop-window-host).

What changed (motivation → approach → change)

An app declares "credentialMasks": ["secrets.json", "tokens/oauth.json"]. Each entry names a file by its path relative to apps/<name>/data/. The app's name comes from where its manifest sits: a built-in package's own name, or an installed app's directory. So one app can't declare a leaf under another app's directory. Escaping, malformed or over-cap entries are refused at install and dropped at spawn. A manifest the parser can't read, however it fails, declares nothing.

Each declared leaf joins the lists a core HIDDEN leaf already sits in, so it gets the same treatment: masked in every mode, write- and link-sealed on macOS, re-anchored under a relocated home, a symlink at the leaf or below the data home refuses the spawn, and a second hard link is masked (inside a data home) or refuses (outside one, reported by kirocrew doctor). A directory at a declared path refuses the spawn, because an entry names a file. On macOS, whose masks are path rules, the folders above each declared file can't be renamed from inside the sandbox; files in them stay writable. The app's own backend, which reads the file, is the one spawn left free to create, rotate and remove those folders.

The masks follow the data. Each entry is also masked at apps/.<name>-data-tmp/, where install and update park data/. The declaration is kept in apps/.<name>-credential-masks.json beside the app directory, so the data a default uninstall keeps stays masked. The gateway refreshes that record whenever it records the installed app, and again before an update or a keep-data uninstall moves the data; if it can't write the record, the update or uninstall refuses before anything moves. Only a manifest that reads cleanly changes the record: a broken, misnamed or invalid app.json leaves it as it was.

The app's own spawned backend gets back only its own declared files, only from the manifest of the code it runs, and only while each is absent or a regular file with one name. A second hard link keeps it masked for the backend too: those bytes may be a core credential's. A declared leaf that is already a core leaf, or a directory holding one, is never lifted. The signature covers a non-empty declaration. APP_SDK_LEVEL goes to 3 (level 2 is ctx.lifecycle, ctx.turns, ctx.untrusted and agentTools).

Where: apps/credential_masks.py holds the grammar, the reader and the record; apps/manifest.py and apps/discovery.py parse, validate, sign and keep the field; apps/manager_records.py, apps/manager_install.py and apps/manager_uninstall.py refresh the record; sandbox_argv.py, sandbox_aliases.py and sandbox_tiers.py mask, judge and lift; apps/backend.py passes the lift; sandbox.py and apps/manager.py name the new symbols. apps/app_sdk_level.py and website/src/app-sdk/sdkLevel.ts carry the level; the specs and docs/app-kit/ describe it.

No shipped built-in declares a mask, so every current sandbox plans byte-identically. Ops Mission Control's core rows stay: its store is at the data-home root, outside its data directory. The PR that moves the app onto this seam relocates the store into apps/ops-mission-control/data/ with a migration and drops the rows, keeping the root name masked as a retired leaf (#32681).

Backwards compatibility

Compatible: the field is new and optional; a manifest without it parses, validates and signs as before (signing_payload adds the key only when non-empty), and with no declaration the sandbox plan, the Seatbelt profile and the apps directory are unchanged (test_a_home_with_no_declaration_plans_as_before, test_no_shipped_built_in_declares_a_mask). For an app that declares nothing, install, update, uninstall, enable and disable write no record and refuse on nothing new. The seam level rises from 2 to 3; every adoption pin requires 1.

Removes nothing: the seam only adds masks; no core leaf, carve-out, seal or tool-gate row is removed or reclassified.

Tests

  • test/test_app_credential_masks.py (new, 78 cases): the entry grammar (lone surrogates included), the manifest round trip, validation and signature; where declarations are read (installed apps, name mismatch, sidecars, malformed and over-deep JSON, cache refresh, per-source read); the namespace plan masks the declared leaf and its move-aside spelling in every mode and under a relocated home; the Seatbelt rules equal a core credential's, and every parent of a declared leaf gets a rename guard (none on the namespace plan); symlinks, linked components and outside hard links refuse, inside ones are masked, any second name refuses on the macOS pass, and a directory at a declared path refuses at both spellings while a directory on the way to a declared file does not; the app's own backend's Seatbelt profile leaves its leaf's folders unguarded while every other spawn keeps them guarded; the backend lift returns only the app's own files, never one hard-linked to token_signing.key or with any second name (until the extra link goes) and never a directory; ../, absolute and impostor declarations reach nothing; a real install writes the record, a default uninstall keeps the kept data masked, a not-JSON, empty, over-deep, misnamed or invalid app.json keeps the record through remember_declaration and a default uninstall, a clean manifest declaring nothing removes it, an uninstall that can't write the record refuses, and an update keeps the parked data masked while the manifest is gone.
  • test/test_app_backend_spawn_env.py::TestTheBackendSpawnLiftsTheAppsDeclaredMasks: start_app_backend passes the app's own declared leaves to extra_visible_dirs, asked with the spawn's provenance. It runs on every OS; TestExecBackendShebangShim keeps its POSIX-only skip.
  • test/integration/conftest.py: the harness reset clears credential_masks._cache between boots, so test_a_second_boot_touches_only_known_module_globals holds.
  • test_app_bridges_agent_configs.py: the built-in snapshot keeps credentialMasks.
  • Mutation-checked: removing the single-name lift rule, the declared-directory refusal, the clean-read rule for the record, the rename guard, the backend's guard exemption, the surrogate rule, the depth catch, any of the three record refreshes or the move-aside spelling each turns at least one case red.
  • test_sandbox_governance_mask.py, test_sandbox_refactor_facade.py, test_manager_facade.py and test_app_backend_composition_contract.py name the new symbols.
  • Determinism: the new file passed 3 repeats under -n 4 and once serially in a fixed-seed shuffled order (seed 32652). Manifest mtimes are set with os.utime, never slept for; no port is bound.
  • Related suites run locally: every test file that references the alias passes, the lift, the record, credential_masks or agentTools, plus the facade-mirror guard, the SDK-level mirror and the app manager and manifest suites (3313 passed), and the flake-pattern ratchet. Semgrep was not run locally (not installed on this host); CI's SAST job runs it.

Proof: not provable -- other: new feature seam with no pre-existing defect to revert onto

Manual verification

Rendered the macOS profile for a scratch home with an app declaring tokens/oauth.json: the declared path gets the same six deny rules as token_signing.key, and apps/demo, apps/demo/data, apps/demo/data/tokens and the move-aside folders get a literal write deny each, none of them without the declaration. Rendered again with that app's lifted targets as extra_visible_dirs, as apps/backend.py passes them: apps/demo/data/tokens has no write deny, so the backend can create it, and the move-aside folders keep theirs.

Screenshots / video

Why no screenshot: the only frontend change is the APP_SDK_LEVEL constant, which renders nothing.

Related Issues

Part of #26967

Follow-up: #32681 (move Ops Mission Control's store into its data directory so its core rows can go)

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners November 7, 2026 22:07
@bolichen97
bolichen97 enabled auto-merge (squash) November 7, 2026 22:07
@bolichen97

Copy link
Copy Markdown
Contributor Author

Seam lane app-credential-masks of the #26967 batch. It is built on owner ruling 3 of 2026-11-07 (#26967 (comment)).

Decision: Ops Mission Control is not moved onto the seam in this PR, so its decoupling-gate rows stay. The ruling limits the seam to leaves under the app's OWN data directory. The store it names, ops_mission_control_secrets.json, is at the data-home root (secrets.py secrets_path() = config_dir() / SECRETS_FILENAME). A manifest declaration can't name it without breaking that limit. Moving the store into apps/ops-mission-control/data/ would change a live credential store's location and require a migration. The root name would also have to stay masked as a retired leaf, because a restored backup can bring it back (the browser-cookies.txt precedent). So the rows can't leave either way, and protection stays byte-identical by leaving them alone. Recorded in ops-mission-control.md, "Repository boundary". A maintainer decides whether the app relocates the store when it leaves core.

Seam level: APP_SDK_LEVEL 1 -> 2. Sibling lanes that also add a level-2 seam make the identical one-line change.

Overlap: Meetings' apps/meetings/data/edits is also a hidden leaf under an app's data dir. It belongs to the app-agent-turns lane (protected subdirs) and is untouched here.

Not run locally: semgrep (not installed on this host; CI's SAST covers it), and the model-pinned local review and cold-reader subagents (no spawn_run in this session).

@github-actions

github-actions Bot commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

Sensitive Change Review

Sensitive files changed:

  • src/kiro_crew/sandbox.py

  • src/kiro_crew/sandbox_aliases.py

  • src/kiro_crew/sandbox_argv.py

  • src/kiro_crew/sandbox_tiers.py

  • @bolichen97 posted a complete reasoning template for cf4d49b.

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 7, 2026
@github-actions

github-actions Bot commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

UX-level review of cf4d49b6e4d0dc981db483db43abb9dced208709 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

UX-Verdict: PASS

Nothing to check. The only website change raises the APP_SDK_LEVEL constant from 2 to 3. The diff adds or changes no dashboard control, label or state, so no screenshot is needed.

[UX-REVIEWED] cf4d49b

Description read

[DESCRIPTION-READ] 6e5ba190d751ccf25b371237c85cf9f5ec23632a489792f32efaf5ff2ea0177e

That sha256 names everything this verdict read: the PR description, plus the 3 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of cf4d49b6e4d0dc981db483db43abb9dced208709 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks. The seam only adds masks: core's rows, carve-outs and gates are unchanged, and the sandbox plans exactly as before when no app declares anything.

Notes

  • One app's data state can now stop every agent spawn. A directory, symlink or extra hard link at a path an app declares makes _refuse_aliased_masked_leaves raise SandboxCeilingUnsealable for every sandbox spawn, not just that app's backend. The keep-data uninstall record keeps that refusal alive after the app is gone. A narrower failure, such as refusing only that app's backend spawn, would contain it.
  • sandbox.py, sandbox_aliases.py and sandbox_tiers.py now import from kiro_crew.apps, so the security core depends on the app layer. Having apps supply the leaves through a small provider in core would keep the dependency pointing one way.

[DESIGN-REVIEWED] cf4d49b

Description read

[DESCRIPTION-READ] 0864d9a46b285b3997bc3bc4b02befe2f8e8200e93a3572a16fcfaf408807c1b

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of cf4d49b6e4d0dc981db483db43abb9dced208709 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

Nothing blocks. The owner approved this seam on #26967 (ruling 3), and every core reader of the manifest field is wired. Its one gap is that nothing in this repository declares a mask yet.

Notes

  • Item 1 — zero in-repo producers: the diff says "No shipped built-in declares a mask". Every credentialMasks reader is in place (38 references in src/ outside apps/credential_masks.py), but the only planned declarer is the follow-up ops-mission-control: move the secret store under its data dir so credentialMasks replaces its core rows #32681. The core rows that make the same app-specific choice still stand (apps/aws-control/data, apps/meetings/data/edits in sandbox_leaves.py). Until one of them moves onto this seam, nothing in the repository runs the manifest-to-sandbox path. Subtraction: none in this PR; deleting those core rows in the follow-up is what gives this seam its consumer.

What this change ships

Inventory (10 items) — 9 justified

Intent: an app can hide its own on-disk credentials from every sandboxed agent process without core naming the app. ADDITION.

  1. An app's manifest can list files under its own data/ that every sandbox hides — zero in-repo producers (see Note)
  2. Declared files stay hidden while install or update parks the data in .<name>-data-tmp/ — justified
  3. New persisted record apps/.<name>-credential-masks.json keeps the masks after a keep-data uninstall — justified
  4. Update and keep-data uninstall now refuse when that record cannot be written — justified
  5. The app's own backend gets its declared files back, only while each has one name — justified
  6. On macOS, the parent folders of declared files cannot be renamed from inside the sandbox — justified
  7. A directory or a symlink at a declared path refuses the spawn — justified
  8. The manifest signature covers a non-empty declaration — justified
  9. The App Kit seam level goes from 2 to 3 — justified
  10. kirocrew doctor reports outside hard links to declared files — justified

[FIRST-PRINCIPLES-REVIEWED] cf4d49b

Description read

[DESCRIPTION-READ] 6d18928a833b63d2d828a5edeec86a81362dc7b8ade22f2c41c208f1cb8913bd

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed cf4d49b6e4d0dc981db483db43abb9dced208709 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] cf4d49b

Verdict parsed from the review's SHA-scoped output markers for commit cf4d49b6e4d0dc981db483db43abb9dced208709.

False positive or not applicable? A repository writer can comment:
/ai-review override fable cf4d49b6e4d0dc981db483db43abb9dced208709 false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of cf4d49b6e4d0dc981db483db43abb9dced208709 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] cf4d49b

False positive or not applicable? A repository writer can comment:
/ai-review override gpt cf4d49b6e4d0dc981db483db43abb9dced208709 false-positive: <reason, 20 to 500 characters>

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 7, 2026
@bolichen97
bolichen97 force-pushed the feat/app-seam-app-credential-masks branch from daab378 to b2aea4d Compare November 7, 2026 23:01
@bolichen97

Copy link
Copy Markdown
Contributor Author

Review fixes, pushed in b2aea4d (amended, rebased on main):

  1. Core HIDDEN leaf un-masked by the backend lift (blocker): fixed. app_declared_mask_targets now drops any declared leaf that is a core leaf of any disposition (_CREW_HIDDEN_LEAVES, _RELOCATED_CREW_HIDDEN_LEAVES, _CREW_READONLY_LEAVES, _CREW_SANDBOX_VISIBLE_LEAVES), and any declared directory that holds one. The exact-match case was the reported one. The directory case belongs to the same class: lifting a parent would expose the core child under it. New tests: test_a_declared_core_leaf_is_never_lifted (meetings declaring edits gets nothing back for apps/meetings/data/edits) and test_a_declared_directory_holding_a_core_leaf_is_never_lifted. Each one fails if the filter is removed or narrowed to exact matches. I corrected the "No carve-out ... reads a declaration" wording in app-kit-platform.md section 35 and in the credential_masks.py docstring.
  2. apps/backend.py call site had no test: fixed. Added TestTheBackendSpawnLiftsTheAppsDeclaredMasks in test_app_backend_spawn_env.py. It runs start_app_backend and checks that an installed app's declared leaves reach extra_visible_dirs. It also checks the provenance passed in: builtin=False for an installed app, True for shipped md-notebook. I ran three mutants: deleting the line, hard-coding builtin=True, and hard-coding builtin=False. Each one turns the class red.
  3. ops_mission_control_secrets.json rows kept: deferred, tracked in ops-mission-control: move the secret store under its data dir so credentialMasks replaces its core rows #32681. Ruling 3 also limits a declaration to the app's own data directory, and this store sits at the data-home root. Removing the rows now would unmask the provider tokens. Moving a live credential store is a data migration that needs its own PR. ops-mission-control: move the secret store under its data dir so credentialMasks replaces its core rows #32681 covers the move, the declaration, and removing the rows (the root name stays masked only as a retired leaf). Both specs and the PR body now link it. I did not edit "Not a goal". This deferral departs from the outcome the ruling states, so it needs an owner's OK. If the owner wants the move in this PR instead, I will do it here.

Gates rerun: black/isort/flake8/mypy, file-line cap, docs-lint, comment-history, brand, harness parity, flake-pattern ratchet, diff_signals.py --check-body (exit 0). The related suites passed (2478 passed).

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 7, 2026
@bolichen97
bolichen97 force-pushed the feat/app-seam-app-credential-masks branch from b2aea4d to 953863d Compare November 7, 2026 23:40
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Nov 7, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author
  • App lifecycle operations leave retained credentials unmasked span=fc1c3ff90f7e

fixed in 953863d: every entry is also masked at apps/.<name>-data-tmp/<entry>, the move-aside name install, update and adopt use for data/.
The declaration is kept in apps/.<name>-credential-masks.json beside the app dir (credential_masks.remember_declaration), read with the manifests, additive only.
Refreshed on every _write_installed (best-effort) and, strictly, before update_app and a keep-data uninstall_app move the data: a record that cannot be written refuses the operation before anything moves.
Tests: TestTheMasksOutliveTheManifestBesideTheData (install writes it, default uninstall keeps kept data masked, unwritable record refuses uninstall, update keeps parked data masked while no manifest stands); each refresh site mutation-checked red.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Seatbelt masks do not protect declared files against parent renames span=261e652dabf1

fixed in 953863d: on Seatbelt every parent of every declared spelling (both data-home prefixes, the move-aside spelling, the relocated home) joins _literal_ancestor_guards, so each directory entry gets a literal file-write* deny and cannot be renamed; contents stay writable (no subpath seal).
The namespace plan is unchanged: a mount moves with a renamed parent. daab378 raised the same finding; this is its fix.
Tests: test_macos_guards_every_parent_of_a_declared_leaf_against_rename, test_namespace_plans_no_parent_guard_for_a_declared_leaf; removing the guard turns the first red.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Directory declarations skip descendant credential hard-link checks span=84e76614317b

fixed in 953863d: sandbox_aliases._declared_directory_files walks each declared directory with no link followed and feeds every regular file below it to the hard-link refusal and to the doctor probe, so an outside hard link refuses and an inside one is masked, as for a declared file.
The walk is capped at 1,024 entries; a walk cut short (cap or unreadable dir) refuses the live home's spawn rather than leave a file unjudged.
Tests: outside link refuses (spawn and doctor), inside link masked, over-cap refuses; each mutation-checked red.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Accepted surrogate paths break sandboxed launches span=fc1c3ff90f7e

fixed in 953863d: entry_error refuses any lone surrogate (U+D800-U+DFFF), so install validation and the spawn-time filter (valid_entries) both drop it before any os.lstat.
Same class, same file: a manifest nested past the parser's depth raised RecursionError past the except; _read_entries now treats it as unreadable, so it declares nothing (daab378 raised both).
Tests: two surrogate spellings in the refused grammar cases and a 100,000-deep body in the unparseable cases; each mutation-checked red.

@bolichen97

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: 953863d
  • What rule changed: app-declared credential masks (credentialMasks in an app's app.json, under its own apps/<name>/data/) gain three sandbox rules: (1) each entry is also masked at the lifecycle's move-aside spelling apps/.<name>-data-tmp/<entry>, with the declaration kept in apps/.<name>-credential-masks.json so kept data stays masked after a default uninstall; (2) on Seatbelt every parent directory of a declared leaf gets a literal file-write* deny (rename guard); (3) the regular files inside a declared directory go through the existing hard-link refusal and the doctor probe (bounded no-follow walk, 1,024 entries).
  • Before -> after (what was allowed/blocked, now): before, an in-sandbox mv of a declared leaf's parent on macOS, a default uninstall, an update's move-aside, or a backup hard link to a file inside a declared directory left the credential readable; now each stays masked or refuses the spawn. A lone-surrogate entry or an over-deep manifest crashed every spawn; now it declares nothing. Core leaves and every app that declares nothing (all shipped apps) plan byte-identically.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): breaks commands only for an app that declares masks: on macOS a sandboxed process cannot rename or remove that app's data folders; a declared directory over 1,024 entries refuses sandboxed spawns until the app lists files instead; an update or keep-data uninstall refuses if the record cannot be written. No secret leaks and no core leaf is unmasked.
  • Evidence checked (which sandbox result proves it): _build_seatbelt_profile renders the literal deny for apps, apps/<n>, apps/<n>/data, apps/<n>/data/tokens and the move-aside parents, none without a declaration, and no subpath seal on the data dir; _spawn_plan (namespace) masks the move-aside spelling and keeps runtime_ancestor_guards unchanged; _refuse_aliased_masked_leaves refuses an outside hard link to secrets/nested/oauth.json and masks an inside one; a real install_app / uninstall_app / update_app keeps the leaves declared while no manifest stands beside the data.
  • No regression:
    • Tools still work (which tools/commands were run, result): the real install, uninstall and update paths in TestTheMasksOutliveTheManifestBesideTheData succeed for a declaring app and for one that declares nothing; kirocrew doctor's probe (masked_credential_leaf_aliases) reports the directory file.
    • Backward compatible (old config / old data / old callers still work, how checked): a manifest without the field parses, signs and plans as before (test_a_home_with_no_declaration_plans_as_before, test_no_shipped_built_in_declares_a_mask); an app declaring nothing gets no record and no new refusal; the namespace plan's guard list is unchanged.
    • Existing tests (which suites passed on this head): locally, 5437 passed in the sandbox / app manager / manifest / backend / discovery / facade suites and 1688 in the spawn-env, governance-mask and manifest files; test_app_credential_masks.py 67 passed (3 repeats under -n 4, one fixed-seed shuffled serial run); black, isort, flake8, mypy, file-line cap, comment-history, brand, harness parity, flake ratchet, docs-lint clean. CI is running on this head.
  • How to undo: revert this PR's commit; no shipped app declares a mask, so nothing on disk depends on it (a stray apps/.<name>-credential-masks.json is then ignored).

@bolichen97

Copy link
Copy Markdown
Contributor Author

Driver decision (campaign autonomy, #26967) on the open question in the review-fix comment above, item 3: keep the ops_mission_control_secrets.json core rows in this PR.

Accepted: the rows stay here. The store is <data home>/ops_mission_control_secrets.json, at the data-home root, so ruling 3 (leaves under the app's OWN data directory only) cannot express it, and dropping the rows now would unmask the provider tokens.
The store moves into apps/ops-mission-control/data/ in the PR that adopts Ops Mission Control onto this seam, with a migration of the live file; the manifest declares it there and the core rows go in that PR. The root name then stays masked as a retired leaf, because a restored backup can bring it back (the browser-cookies.txt precedent). Tracked in #32681.
Two related shape decisions for this PR: installed app trees stay sandbox-writable (sealing them read-only would widen sandbox scope, which only the operator can choose; the rename guards in 953863d deny renaming the folders above a declared file and nothing else), and APP_SDK_LEVEL stays 2.

The frozen Goal / Why it matters / Not a goal sections are unchanged.

@bolichen97
bolichen97 force-pushed the feat/app-seam-app-credential-masks branch from b5a3345 to 1ead9c1 Compare November 8, 2026 06:49
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: passed Eligible automated validation passed for the current revision labels Nov 8, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author

Conflict-only rebase: b5a33456ab -> 1ead9c1ad6, onto main 1929944186 (DIRTY after #32659 merged). Requesting a quick re-approval; the force-push dismisses the earlier one.

git range-diff b5a33456ab~1..b5a33456ab origin/main..1ead9c1ad6 differs in one hunk only:

  • docs/app-kit/api-reference.md, the ctx.sdk_level paragraph: feat(apps): add app kit agent-turn and untrusted-text seams #32659 rewrote the level 2 sentence to add ctx.turns and ctx.untrusted, and this PR adds the level 3 clause for credentialMasks. The resolution keeps both: level 2 = ctx.lifecycle + ctx.turns + ctx.untrusted, level 3 = credentialMasks.
  • Every other file in the commit is unchanged apart from context lines. APP_SDK_LEVEL stays 3 (main is 2), and website/src/app-sdk/sdkLevel.ts still mirrors it.

Gates on this head: 2539 passed in the touched and related tests (including #32659's test_app_agent_turn_sdk.py and test_app_untrusted_text_sdk.py). flake8, isort, the black gate, mypy, comment-history, brand, docs-lint and the file-line cap all pass. diff_signals.py --check-body passes, so the PR body needs no edit. Auto-merge is still armed (squash). The Sensitive Change Review template is re-posted below for the new head.

@bolichen97

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: 1ead9c1
  • What rule changed: app-declared credential masks (credentialMasks in an app's app.json, under its own apps/<name>/data/) join the core HIDDEN lists: each entry is masked in every mode at apps/<name>/data/<entry> and at the move-aside spelling apps/.<name>-data-tmp/<entry> (declaration kept in apps/.<name>-credential-masks.json); on Seatbelt every parent of a declared leaf gets a literal file-write* deny, except for the spawn that lifts the leaf (the app's own backend); regular files inside a declared directory go through the hard-link refusal and the doctor probe (bounded no-follow walk, 1,024 entries), and a second name inside the same declared directory is covered by its mask.
  • Before -> after (what was allowed/blocked, now): before, an app's on-disk credential under its data directory was readable by any sandboxed agent process unless core named it; now it is masked or the spawn refuses (symlinked leaf, outside hard link). Core leaves and every app that declares nothing (all shipped apps) plan byte-identically. This head is a conflict-only rebase of b5a3345 onto main 1929944 (after feat(apps): add app kit agent-turn and untrusted-text seams #32659): no sandbox file differs from b5a3345; the one conflict was a doc sentence in docs/app-kit/api-reference.md.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): breaks commands only for an app that declares masks: on macOS a sandboxed process other than the app's own backend cannot rename or remove that app's data folders; a declared directory over 1,024 entries refuses sandboxed spawns until the app lists files instead; an update or keep-data uninstall refuses if the record cannot be written. No secret leaks and no core leaf is unmasked.
  • Evidence checked (which sandbox result proves it): test/test_app_credential_masks.py pins the namespace plan's masks for both spellings, the Seatbelt literal denies (none without a declaration, none on the lifting backend's own profile), the alias pass refusing an outside hard link and masking an inside one, and the real install / uninstall / update paths keeping the leaves declared.
  • No regression:
    • Tools still work (which tools/commands were run, result): real install_app / uninstall_app / update_app in TestTheMasksOutliveTheManifestBesideTheData succeed for a declaring app and for one that declares nothing; start_app_backend passes only the app's own leaves (TestTheBackendSpawnLiftsTheAppsDeclaredMasks).
    • Backward compatible (old config / old data / old callers still work, how checked): a manifest without the field parses, signs and plans as before (test_a_home_with_no_declaration_plans_as_before, test_no_shipped_built_in_declares_a_mask); APP_SDK_LEVEL is 3 here because level 2 on main covers ctx.lifecycle (feat(apps): add ctx.lifecycle and wait for an app-opened session #32648) plus ctx.turns and ctx.untrusted (feat(apps): add app kit agent-turn and untrusted-text seams #32659); every adoption pin requires 1.
    • Existing tests (which suites passed on this head): locally 2539 passed on this head across test_app_credential_masks.py, test_app_backend_spawn_env.py, test_sandbox_governance_mask.py, test_sandbox_refactor_facade.py, test_app_sdk_level_mirror.py, test_app_manifest_desktop.py, test_app_manifest*.py, the composition and bridges contracts, plus feat(apps): add app kit agent-turn and untrusted-text seams #32659's test_app_agent_turn_sdk.py and test_app_untrusted_text_sdk.py; black, isort, flake8, mypy, comment-history, brand, docs-lint, file-line cap clean. CI is running on this head.
  • How to undo: revert this PR's commit; no shipped app declares a mask, so nothing on disk depends on it (a stray apps/.<name>-credential-masks.json is then ignored).

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running and removed readiness: checking Automated validation is still running merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: action required A blocking check or review needs attention labels Nov 8, 2026
An app lists files under its own data directory in a new
`credentialMasks` manifest field, and every sandbox hides each one as
it hides a core HIDDEN crew-home leaf: masked in every mode, sealed on
Seatbelt, re-anchored under a relocated home, refused when reached
through a symlink, and masked or refused on a second hard link. Only
the app's own backend gets its declared leaves back, from the manifest
of the code it runs. Entries outside the app's data directory are
refused, so the seam only adds masks. APP_SDK_LEVEL becomes 3.

No built-in declares a mask yet, so every current sandbox is
unchanged. Ops Mission Control's secret store sits at the data-home
root, outside its data directory, so its core rows stay.

Part of #26967
@bolichen97
bolichen97 force-pushed the feat/app-seam-app-credential-masks branch from 1ead9c1 to cf4d49b Compare November 8, 2026 08:24
@bolichen97

Copy link
Copy Markdown
Contributor Author
  • A declared hard-link alias exposes a core credential to an app backend span=84e76614317b
    resolution: narrowed -- entries name files only; the directory walk, its cap and both declared-directory cover rules are removed, and the backend lift hands back only a single-name file

fixed in cf4d49b: sandbox_tiers._liftable_declared_file (lstat, no link followed) lets app_declared_mask_targets hand back a declared spelling only while it is absent or a regular file with one name, at every spelling, so a declared name hard-linked to token_signing.key (or with any second name) stays masked for the app's own backend too.
That rule is what makes _inode_aliases_under counting a declared name as cover true: such a name is masked for every spawn, the backend's included.
Same class, narrowed rather than patched: a directory at a declared path now refuses the live home's spawn, so _declared_directory_files, the 1,024-entry cap, the declared-directory masked_dirs prefix and the path-only renameable exception are deleted; core accounting is main's.
Tests: test_a_declared_file_hard_linked_to_a_core_credential_is_never_lifted (the exact trigger), test_a_declared_file_with_a_second_name_anywhere_is_never_lifted, test_a_directory_at_a_declared_path_is_never_lifted, test_a_directory_at_a_declared_path_refuses_the_spawn[data|staged], test_a_path_only_platform_refuses_any_second_name; removing the lift rule or the directory refusal turns them red.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • A failed manifest read deletes retained credential protection span=fc1c3ff90f7e

fixed in cf4d49b: remember_declaration reads through credential_masks._clean_declaration, which returns None (not ()) unless app.json is a regular file under the size cap, parses as an object with the right name and has a valid credentialMasks.
On None the record is left exactly as it is and a warning names the manifest; only a clean manifest declaring nothing removes the record.
All three callers (_write_installed, update_app before the move, a keep-data uninstall_app) go through that one function, so the class has one site.
Tests: test_a_manifest_that_does_not_read_cleanly_keeps_the_record[not-json|empty|nested-past-the-parser-depth|misnamed|invalid-entry] (record unchanged after the refresh and after a real default uninstall, kept data still masked) and test_a_clean_manifest_declaring_nothing_removes_the_record; reading through _read_entries again turns all five red.

@bolichen97

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: cf4d49b
  • What rule changed: app-declared credential masks (credentialMasks in an app's app.json, under its own apps/<name>/data/) join the core HIDDEN lists: each entry is masked in every mode at apps/<name>/data/<entry> and at the move-aside spelling apps/.<name>-data-tmp/<entry> (declaration kept in apps/.<name>-credential-masks.json, rewritten or removed only by a manifest that reads cleanly); on Seatbelt every parent of a declared leaf gets a literal file-write* deny, except for the spawn that lifts the leaf (the app's own backend); an entry names a file, so a directory at a declared path refuses the live home's spawn; the backend gets a declared file back only while it is absent or a regular file with one name.
  • Before -> after (what was allowed/blocked, now): against 1ead9c1, a declared name hard-linked to a core credential (or with any second name) is no longer handed to the app's backend, a malformed app.json no longer deletes the retained record before a keep-data uninstall, and the declared-directory walk (1,024-entry cap) is gone in favour of refusing a directory at a declared path. Core leaves and every app that declares nothing (all shipped apps) plan byte-identically; the hard-link accounting for core leaves is main's.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): breaks commands only for an app that declares masks: a directory at a declared path refuses sandboxed spawns until it is moved or its files are listed; a declared file with a second hard link stays masked for the app's own backend until the link is removed; on macOS a sandboxed process other than the app's own backend cannot rename that app's data folders; an update or keep-data uninstall refuses if the record cannot be written. No secret leaks and no core leaf is unmasked.
  • Evidence checked (which sandbox result proves it): test/test_app_credential_masks.py pins the lift excluding a declared file hard-linked to token_signing.key, any multi-linked file and a directory; the alias pass refusing a directory at both spellings; the record surviving five malformed-manifest shapes through a real default uninstall; plus the earlier plan, Seatbelt and lifecycle cases. Each new production rule was removed once and turned its tests red.
  • No regression:
    • Tools still work (which tools/commands were run, result): real install_app / uninstall_app / update_app in TestTheMasksOutliveTheManifestBesideTheData succeed for a declaring app and for one that declares nothing; start_app_backend passes only the app's own leaves (TestTheBackendSpawnLiftsTheAppsDeclaredMasks).
    • Backward compatible (old config / old data / old callers still work, how checked): a manifest without the field parses, signs and plans as before (test_a_home_with_no_declaration_plans_as_before, test_no_shipped_built_in_declares_a_mask); APP_SDK_LEVEL is 3; every adoption pin requires 1.
    • Existing tests (which suites passed on this head): locally 3313 passed across every test file referencing the alias passes, the lift, the record, credential_masks or agentTools, the facade-mirror guard, the SDK-level mirror and the app manager and manifest suites; the new file passed 3 repeats under -n 4 and a fixed-seed shuffled serial run; black gate, isort, flake8, mypy, comment-history, brand, docs-lint, harness parity, file-line cap and the flake ratchet clean. CI is running on this head.
  • How to undo: revert this PR's commit; no shipped app declares a mask, so nothing on disk depends on it (a stray apps/.<name>-credential-masks.json is then ignored).

This push fixes the two GPT findings on 1ead9c1 (dispositions above) and rebases onto main ece4f407e2; the force-push dismisses the earlier approval, so a re-approval is needed. The conflict with #32660 (agentTools) kept both fields in apps/manifest.py and the api-reference sentence; #32652's spec section is now §37 because main's §36 is the worker auto-approve seam.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: passed Eligible automated validation passed for the current revision and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Nov 8, 2026

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This review checked head cf4d49b. The credentialMasks grammar refuses absolute paths, .. and empty segments, backslashes, colons and control characters. The app name comes from where the manifest sits, so one app cannot declare paths in another app's data directory. A manifest that does not read cleanly yields no masks and does not refuse spawns. Declared leaves join the existing hidden-leaf, hard-link and relocated-home lists. Update and keep-data uninstall roll back if the record cannot be written. The review re-ran test_app_credential_masks.py on this head and all 78 cases passed. Two control mutations went red as expected.

Done well: the seam is strictly additive. A home whose apps declare nothing plans the same sandbox as before, and a test pins that.

Security: the backend lift hands a path back only while it is absent or a regular file with one name. It drops core leaves and the directories that hold one, so it cannot reopen a core mask or return core credential bytes through a hard link. Banning the backslash means an entry can never break out of a quoted macOS sandbox profile string. The PR body discloses the remaining gap: an agent that rewrites app.json and deletes the record removes that app's masks for its next spawn. Before this PR no app mask existed at all, so nothing regresses.

Optional:

  • Add a Seatbelt test under a relocated data home for a nested entry such as tokens/oauth.json. If the relocated operand of app_mask_parents in sandbox_argv.py is removed today, no test goes red.
  • A misdeclared directory, symlink or extra hard link at one app's leaf refuses every sandboxed spawn on the host, and the retained record keeps that refusal after a keep-data uninstall. Consider naming the app and apps/.<name>-credential-masks.json in the refusal message so an operator can recover.
  • Open PR #32983 also claims APP_SDK_LEVEL = 3. Name the merge order in both bodies. Whichever PR lands second should move to level 4.

@bolichen97
bolichen97 merged commit fc2d4fe into main Nov 8, 2026
162 of 164 checks passed
@bolichen97
bolichen97 deleted the feat/app-seam-app-credential-masks branch November 8, 2026 10:04
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 8, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants