For developers · App internals
System permissions
On this page
Which permissions Gitoodo needs on macOS and Windows, per build type, when the system asks, what the app does when the user declines, and where the decision comes from. Principle (Apple HIG "Privacy", Microsoft "Windows app privacy guidance"): ask in context, only when the feature needs it, explain calmly before the system prompt, and never block the app when a permission is denied; show a hint that leads to the system settings.
Build types:
- macOS direct: Developer ID, hardened runtime, notarized, not sandboxed (
Entitlements.direct.plist). - macOS App Store: sandboxed (
Entitlements.appstore.plist, Cargo featurestore, config overlaytauri.appstore.conf.json). - Windows direct: unpackaged installer, full trust.
- Windows MSIX: packaged for the Microsoft Store (
src-tauri/windows/AppxManifest.template.xml).
Matrix#
| Purpose | macOS direct | macOS App Store | Windows direct | Windows MSIX |
|---|---|---|---|---|
| Network to forges (HTTPS) | no entitlement needed | com.apple.security.network.client | none | capability internetClient |
| Forge on the local network | Local Network prompt (NSLocalNetworkUsageDescription); ATS NSAllowsLocalNetworking | same, plus network.client | none (firewall prompt is the system) | privateNetworkClientServer |
| Skill install into agent skills folders | writes directly (not sandboxed) | folder dialog (files.user-selected.read-write), explanation first | writes directly | writes directly (runFullTrust) |
| Notifications | UNUserNotificationCenter, authorization at start or first send; denial shown | same (sandbox needs no entitlement) | no prompt; hint to Notifications settings | same |
| Start at sign-in | LaunchAgent via the autostart plugin; hint to Login Items | SMAppService.mainApp (macOS 13+) | autostart plugin (registry) | windows.startupTask, see store |
| Menu bar / tray only, no Dock icon | LSUIElement | LSUIElement | none | none |
| Tokens | Data protection keychain (group entitlement + profile), file-based fallback; see Keychain | same group; see Keychain | Credential Manager, no prompt | Credential Manager, no prompt |
Prompt timing and behaviour when denied#
- Local network (macOS): the system asks on the first connection to a local host. The app does not
pre-prompt. When the connection to a local forge fails, the wizard shows a calm note with the action
"Systemeinstellungen öffnen" (
Privacy_LocalNetwork). Only shown for local hosts on macOS (local_network_hint_applies). - Notifications (macOS): Gitoodo asks for alert and sound authorization at start once an account and a notification type are set up, and again before every send (the system only prompts while undecided). The settings page reads the state the same way: on a denial it says so ("Mitteilungen sind ausgeschaltet"), otherwise it keeps the general note; both lead to the Notifications pane. See Notifications on macOS.
- Notifications (Windows, Linux): the Tauri notification plugin reports the permission as granted, so
a denial cannot be detected; the page keeps the general note with the action
"Systemeinstellungen öffnen" (
ms-settings:notifications). A failed send is logged. - Start at sign-in: toggled by the user on the autostart page. When it fails (denied or pending approval
in Login Items), the page shows the error with the action "Systemeinstellungen öffnen"
(
com.apple.LoginItems-Settings.extension,ms-settings:startupapps). - First-run onboarding (#94, #617): shown on first launch, whenever no account exists, and from
"Hilfe & Feedback → Erste Schritte". It runs in its own centred window (980 x 680, clamped to the
screen; its frame is never stored as the window frame) with named phases on top: Willkommen,
Konto, Repos, Arbeitsweise, Mitteilungen & Start, Fertig. Enter runs the main action and Esc goes
back, except in text fields. The repo step switches repos on or off with the same
disabled_reposas Settings → Repos and leaves orchestration rules alone. Its notification step asks only on the button "Mitteilungen erlauben" and shows the denied hint with the Notifications pane; its autostart step (on by default) shows the same error and Login Items action as the autostart page. Progress is stored in the settings (onboarding), so every step can be skipped and an interrupted run resumes; closing the window pauses it and the next tray click reopens it. Finishing ("Zum Überblick", or "Orchestrator einrichten" for the setup assistant) turns the window into the regular detached window (finish_onboarding_window, seedocs/window-frame.md), where the overview and the introduction tour (or the setup assistant) follow. - Skill folder (App Store build only): the skill page explains why
~/.claudeis needed and what is written (onlygitoodo-questions), then opens the folder dialog. A folder not named.claudeis rejected with a hint; cancelling changes nothing. The direct build skips this step.
The system settings deep links are in src-tauri/src/permissions.rs (settings_url).
Notifications on macOS (#131)#
Symptom: on macOS 27 no notification appeared and Gitoodo was missing from System Settings > Notifications.
Root cause: the Tauri notification plugin (2.x) posts through notify-rust and
mac-notification-sys, which use the deprecated NSUserNotificationCenter. Before the first post,
mac-notification-sys looks up a bundle id with an AppleScript (get id of application ..., blocked
in the sandbox and failing anyway), falls back to com.apple.Finder/com.apple.Terminal and swaps
the implementation of NSBundle.bundleIdentifier. Notifications were therefore posted under another
app's identity; Gitoodo never registered with Notification Center and never asked for authorization.
The plugin spawns the post and returns success, and its desktop permission check always answers
"granted", so nothing was logged.
Fix: on macOS the plugin is not linked any more. src-tauri/src/notify_macos.rs uses
UNUserNotificationCenter through the safe objc2-user-notifications bindings (no unsafe):
requestAuthorizationWithOptions (alert, sound), then addNotificationRequest with a unique
identifier. It only runs inside an .app bundle (an unbundled cargo/dev binary would make the
center raise); outside, a warning is logged and nothing is posted. Failures are logged as
notification_error with a reason (authorization_failed, rejected, no_app_bundle), never with
the notification text. Windows and Linux keep the plugin and now log a failed send.
Limits: the error object of a failed request is not read (that would need unsafe), so the log has
the reason but not the system's error code. The permission state comes from the authorization answer,
because reading UNNotificationSettings from its completion handler also needs unsafe. There is no
notification-center delegate, so a banner may be held back while Gitoodo's own window is in front.
Notifications on macOS: prompt shown in the background (#166)#
Symptom: after #131 the permission request did not appear and Gitoodo was missing from System Settings > Notifications.
Evidence (unified log of the installed, Developer ID signed, sandboxed /Applications/Gitoodo.app,
macOS 27.2): usernoted registers the bundle at the first request ("Sending request for permission
for <bundle id>"), but the prompt record is alertStyle:"none" with response action: closed and the settings read authorizationStatus: Denied; the authorization was only set to
"allow" seven seconds later, by hand. Signing, bundle identity and sandbox are therefore fine: the
center is reached (Creating a user notification center, didGrant) and later banners were
delivered (Presenting ... alertStyle:"banner"). The app log has no notification_* event because
nothing failed.
Cause: the request is made at start from a menu-bar app (LSUIElement, accessory policy) that is
not the active app, so the system shows the prompt as a quiet banner that closes by itself. It is
counted as not allowed, and the user never saw a dialog.
Fix: the first authorization request of an installation (marker file notification-prompted in the
config dir, notify::first_prompt) activates the app first (NSApplication.activate, main
thread, safe bindings), so the prompt is shown to the user. Later requests stay silent. Not
reproducible here without wiping the notification database, so the fresh-install check
(prompt visible, entry in System Settings > Notifications, question and #73 reminder as banners)
needs a human on a clean install.
Open: without a notification-center delegate a banner is still held back while Gitoodo's own window
is in front (needs unsafe, which the crate forbids).
Keychain#
Tokens and the chat webhook URL live in the OS credential store (crates/core/src/secrets.rs).
On macOS the app uses the data protection keychain (#126): items belong to a keychain access group
and carry no per-app access list, so the direct, App Store and dev builds that share the group read
the same token without any prompt (TN3137, "Sharing access to keychain items"). The group is
Q7V3X27S2U.de.gitoodo.app (team id plus bundle id), the first keychain-access-groups
entry, hence the default group of new items; the code sets no group. The direct build lists the
group of the former identifier online.lindstedt.gitoodo (Gitoodo 0.1.x, #595) second, only so the
one-time move (crates/core/src/identity_migration.rs) can copy the tokens out of it without a
prompt; its Developer ID profile allows Q7V3X27S2U.*. Remove that entry once no 0.1.x install
is left (scripts/check-identifier.py allows exactly this line).
Items of older versions live in the file-based keychain and are described below.
Entitlements. keychain-access-groups is restricted: the data protection keychain needs
keychain-access-groups or com.apple.application-identifier, and both must be authorized by an
embedded provisioning profile (TN3125, TN3137). A signed app that claims them without a matching
profile is killed at launch, so they are not in the default plists. The extra plists
(Entitlements.direct.keychain.plist, Entitlements.appstore.keychain.plist) and the overlays
src-tauri/tauri.keychain.direct.conf.json / tauri.keychain.appstore.conf.json (add
--config after the usual config) set the entitlements and embed the profile from
src-tauri/profiles/{direct,appstore}.provisionprofile (ignored by git, account specific). The
sandbox of the store build needs no further keychain entitlement. Without the profile (plain
build, dev, ad hoc) the app gets errSecMissingEntitlement (-34018) and uses only the
file-based keychain; the prompt hint stays. Builds with the entitlement keep a shared copy there for
exactly these builds (see "Migration and mixed builds").
Profiles (Apple Developer account). Created 2026-11-10 through the App Store Connect API (global key in ~/.config/appstoreconnect/api_key.json, POST /v1/bundleIds and POST /v1/profiles, types MAC_APP_DIRECT with the Developer ID Application certificate and MAC_APP_STORE with the Apple Distribution certificate); the portal steps below are the manual equivalent. The App ID did not exist yet and was created with the same call. The App Store profile expires 2027-04-19 with its certificate and must be recreated then. Since #595 (2026-11-16) the App IDs are de.gitoodo.app and de.gitoodo.app.service with Developer ID profiles for both; an App Store profile for de.gitoodo.app does not exist yet:
- Identifiers: App ID
de.gitoodo.appexists; no extra capability is needed for keychain sharing on macOS (the group is derived from the team id and the profile's application identifier). - Profiles, "Developer ID" (macOS): create a Developer ID provisioning profile for the App ID
with the Developer ID Application certificate; save as
src-tauri/profiles/direct.provisionprofile. - Profiles, "Mac App Store Connect": create a profile for the same App ID with the Apple
Distribution certificate; save as
src-tauri/profiles/appstore.provisionprofile. - Build with the overlay (direct:
tauri build --config src-tauri/tauri.keychain.direct.conf.json; store: additionally--features storeand theappstoreconfigs, then the keychain overlay last). The profile's team and application identifier must equal the plist values.
Background services (#594). The classifier and dispatcher run as launchd agents in their own process, not in the app, so they need the token too, without any prompt: a background process cannot answer one. Apple's model for this is the data protection keychain with a keychain access group that every program of the team claims (TN3137; "Sharing access to keychain items among a collection of apps"). Access groups are restricted entitlements that must be authorized by an embedded provisioning profile, and a bare command-line executable cannot embed one; the documented way is to wrap the program in an app-like bundle ("Signing a daemon with a restricted entitlement"). Hence, in a Developer ID build with both profiles:
Gitoodo.app/Contents/Helpers/GitoodoService.appis the service helper (Apple: "Placing content in a bundle", helper tools go toContents/Helpers): thegitoodoCLI, signed with identifierde.gitoodo.app.service, entitlementssrc-tauri/Entitlements.service.plist(App IDQ7V3X27S2U.de.gitoodo.app.service, keychain groupQ7V3X27S2U.de.gitoodo.app, the app's group, listed first) and its own profilesrc-tauri/profiles/service.provisionprofile.Info.plistfromsrc-tauri/macos/GitoodoService.Info.plist(background only).scripts/mac-service-helper.shbuilds and signs it inside out and seals the app again;scripts/build-local-mac.sh(and so the release) runs it and the app's keychain overlay when both profiles exist. Without them the build stays as before.- macOS 13+: the agents are login items of the app, registered with
SMAppService.agent(plistName:)(crates/core/src/login_items.rs). Their property lists ship sealed in the bundle,Gitoodo.app/Contents/Library/LaunchAgents/de.gitoodo.app.{daemon,dispatcher}.plist(sourcesrc-tauri/macos/LaunchAgents/, added bysrc-tauri/tauri.sidecar.conf.json), and name the program relative to the bundle (BundleProgram, which launchd supports only for plists installed with SMAppService,man launchd.plist).mac-service-helper.shpointsBundleProgramat the helper before it seals the app; without the helper it staysContents/MacOS/gitoodo. The agents run directly inside the bundle: nothing is copied, an app update is an agent update, signature, entitlements and profile stay as signed. Details below ("Login items"). - Older installs, macOS 11 and 12 (no SMAppService) and builds without the bundled plists (dev runs
from a build folder;
GITOODO_SERVICE_MANAGER=launchdforces it): installing the services (cli_install::install_service) copies the plain CLI and the whole helper bundle to~/Library/Application Support/de.gitoodo.app/bin/and writes plists to~/Library/LaunchAgentsthat runbin/GitoodoService.app/Contents/MacOS/gitoodo. A bundle copy keeps signature, entitlements and profile (checked withcodesign --verify --strict; a failed check falls back to the plain CLI). An app update replaces the copy when the helper or its profile changed (refresh_outdated_services). - Reads: the helper is in the group, so
load_tokenfinds the token in the data protection keychain without a prompt; its check of the shared file-based copy is silent and ignored when refused. A token still only in the file-based keychain (older versions) moves on the app's own silent read: the app reads every account before it asks the services (grant_where_needed), so existing tokens migrate once without user action.gitoodo token-accessthen answersreadable, the setup counts the services as ready, and no approval step, dialog or error appears. - The shared file-based copy stays (see "Migration and mixed builds"): the plain terminal CLI, dev and ad hoc builds have no group and read only that copy.
- Fallback without the helper (unsigned, ad hoc, dev, forks, a build without the profiles): the
services run the plain CLI and read the file-based item; the app grants them access once
(
token-access --grant, issue #594 step 1) and the setup shows the inline approval while a service still needs it. - Uninstall:
scripts/uninstall.shfirst unregisters the login items the documented way (Gitoodo.app/Contents/MacOS/gitoodo service uninstall all, i.e.SMAppService.unregister(); deleting the app ends them too) and boots out every label, then runsgitoodo token-purgethrough the installed or bundled helper (only a binary in the group can delete data protection items;securityreaches only the file-based keychain), then removes the file-based items as before. - Store build: sandboxed, no services, nothing to do.
Profiles for the helper (Apple Developer account, once; same way as the app's profiles above):
- Identifiers: register the App ID
de.gitoodo.app.service(explicit, macOS). No capability needs to be switched on; Developer ID profiles grantkeychain-access-groupsQ7V3X27S2U.*(checked in the app'sdirect.provisionprofile). - Profiles, "Developer ID" (macOS): a profile for that App ID with the Developer ID Application
certificate; save it as
src-tauri/profiles/service.provisionprofile(ignored by git). - Build with
bash scripts/build-local-mac.sh; it checks that the profile authorizes the claimed App ID and that helper and app claim the same group.
Not verified by the change itself (needs a signed build and a fresh macOS account): the silent read on a fresh install and after an update, the local network prompt of the helper for a forge in the LAN.
Login items (#594 step 2b, crates/core/src/login_items.rs, service_install.rs). Apple's
references: SMAppService, agent(plistName:), register(), unregister(), status
(SMAppService.Status), openSystemSettingsLoginItems(), "Updating your app package installer to
use the new Service Management API", man launchd.plist (BundleProgram,
AssociatedBundleIdentifiers).
- Who registers: the app (setup, "Set up service", the doctor's fixes) and the CLI inside the
bundle (
Gitoodo.app/Contents/MacOS/gitoodo service install, also through the~/.local/binlink ofinstall.sh). The framework attributes the agent to the bundle the calling executable belongs to; a copy outside the bundle (the stable CLI inbin/) getsnotFoundand keeps thelaunchctlway; asked to change an existing login item it points to the app. - Status:
enabledcounts as installed;requiresApprovalcounts as installed too (registered, runs once allowed): the setup and the/doctorsay so and offer "Open Login Items" (open_login_items,openSystemSettingsLoginItems());notRegisteredandnotFoundare not installed.gitoodo doctorprints the registration of each service. - Start, stop, switch-off: launchd knows the job under the same label, so
launchctl kickstart,bootoutanddisablework as before ("Quit everything", #737). A login item has no plist to bootstrap: it loads again by registering (register()loads a booted-out job and lifts alaunchctl disable; measured on macOS 27). - Logs: a sealed plist cannot name a per-user
StandardErrorPath; the plists setGITOODO_SERVICE_STDERR=1and the service sends its stderr to the same~/Library/Logs/de.gitoodo.app/<service>.stderr.logitself. - Updates: an update replaces the program the running agents execute. On launch the app compares
the program file with the one it last started (
service-program.stampin the state folder) and restarts running agents (kickstart -k);install.shdoes the same for labels launchd reports asmanaged_by = com.apple.xpc.ServiceManagement. When launchd refuses the new program (an ad hoc rebuild changes the code directory hash it recorded), the agent is unregistered and registered again. A switched-off service stays off. - Moving older installs (once,
migrate_to_login_items, at app start and before every install): per old plist agent:bootoutand wait, delete the plist,register(), switch it off again if the user had switched it off; then deletebin/GitoodoService.app. Logs, settings, state and the plain CLI copy for the terminal stay. Ifregister()fails the old plist is restored and loaded again and the move is retried at the next start. The test build (test-access) never moves or restarts services on its own, but shares the labels with an installed release: its CLI (service install) does replace them. - Unsigned and dev builds: SMAppService also works with ad hoc signatures and outside
/Applications(measured on macOS 27); a registration that fails with a signature, plist or availability error falls back to thelaunchctlway with the plain CLI copy and says so.
Migration and mixed builds (#236). Builds with and without the entitlement can run on the same Mac (direct build with profile next to a store preview without profile, dev or ad hoc). A build without the entitlement cannot see the data protection keychain, so a build with it keeps the token in both keychains: its own copy in the data protection keychain and the shared copy in the file-based keychain that every build reads. Until #236 the first read moved the token and deleted the file-based item; every build without the entitlement then failed with "no token stored for this account".
- Read, with entitlement: the data protection keychain is asked first. If it has no item, the
file-based item is read (background: without prompt, so an item of another build yields
accessNeededand the existing hint; interactive: the one-time prompt), copied to the data protection keychain and kept. If it has an item, the shared copy is read without prompt as well: a different value wins (another build changed the token) and is copied over; a shared copy that needs approval leaves the build on its own copy. - A token only in the data protection keychain: if the mirror marker (data protection keychain,
service
gitoodo.mirrored, value without secret) is present, a build without the entitlement removed the account; the copy and the marker are removed and the account readsmissing, so no removed token comes back. Without the marker the item was moved by an older version; the shared copy is restored (created by this build, so a build without the entitlement asks once through the existing hint). - Save: the shared copy first (a failure changes nothing, it may need the prompt when the item belongs to another build), then the data protection copy and the marker.
- Remove: shared copy first, then the data protection copy, the marker last. A build without the entitlement removes only the shared copy; the next read of a build with the entitlement finishes the removal through the marker.
- Without the entitlement everything stays in the file-based keychain.
Failures to copy or restore keep the existing items, still return the token and are logged
(keychain_access op migrate, throttled); the next read tries again. A token moved by a version
before #236 reaches a build without the entitlement only after a build with the entitlement has run
the fixed version once. Tests: secrets.rs (migration_*, mixed_builds_*, token_moved_*,
without_entitlement_*, set_*, delete_*).
Verified on the Mac (2026-11-10): both profiles carry com.apple.application-identifier
Q7V3X27S2U.de.gitoodo.app and the keychain group. The direct build with the overlay embeds
the profile, passes codesign --verify --strict --deep and launches. The keyring_roundtrip test binary,
wrapped in a bundle with the same profile and entitlements and signed with Developer ID, stores, reads
and deletes a token without any dialog. The store build embeds its profile and is correctly signed, but a
Mac App Store profile cannot be launched outside TestFlight or the App Store, so its keychain run is open.
Not verified here: the cross-build read without prompt on the real Mac, a launch of the App Store build.
When macOS asks for the old file-based keychain (item created by build A, read by build B; builds without the keychain entitlement read it, builds with it keep the shared copy there):
| Build A → build B | Prompt |
|---|---|
| Same build type, regular update (same bundle id and team) | no, the designated requirement matches (verified, see below) |
| Reinstall of the same build type | no; the item stays in the login keychain |
| Developer ID ↔ App Store build | yes, once, different signing identity |
| Restored backup (Time Machine, Migration Assistant) | no for the same build type; the keychain file and its access lists are restored with it |
| Changed signing identity, same team (renewed certificate) | no; the requirement checks the team id, not the certificate |
| Changed signing identity, other team or bundle id | yes, once |
Dev build (tauri dev, ad hoc or unsigned) ↔ release | yes, once; ad hoc signatures change (verified, see below) |
| Windows Credential Manager, any build | never; access is bound to the user |
"Always Allow" adds the reading build to the item's access list, so the question does not come back for that build. "Allow" grants the single read only; the next start asks again. "Deny" leaves the item untouched.
Local builds on the Mac (#364): a plain npm run tauri build without a signing identity is signed
ad hoc. Its designated requirement is the build's cdhash, so every new build is a different app
for the keychain and "Always Allow" from the previous build no longer applies; macOS asks again
and wants the login password. Build local preview apps with the Developer ID identity instead:
bash scripts/build-local-mac.sh # build and check the signature
bash scripts/build-local-mac.sh --install # also replace /Applications/Gitoodo.app and start itThe script picks the first Developer ID Application identity from the keychain (or
APPLE_SIGNING_IDENTITY), refuses an ad hoc result and prints the designated requirement
(bundle id plus team id). After the switch from an ad hoc build, macOS asks once more; answer it
with "Always Allow". Later builds keep the same requirement and read the token without a prompt.
App behaviour:
- Background reads (every sync) run with keychain user interaction switched off
(
SecKeychainSetUserInteractionAllowed, guard insecrets.rs). A read that would prompt fails witherrSecInteractionNotAllowed(-25308) and becomes the stateaccessNeeded; no dialog appears out of context and the sync does not report "server unreachable". Current macOS reports a refused access list check without interaction aserrSecAuthFailed(-25293, measured on Darwin 27); a background read cannot have been declined, so it also becomesaccessNeeded(background_read_error). - The popover then shows a calm note per account instead of the red error bar
(
shell-keychain-<account>): why the token is needed, that macOS asks once, to choose "Always Allow" and enter the Mac login password. Its action (shell-keychain-<account>-action) callsunlock_keychain, which reads once with the prompt allowed and starts a sync. - "Deny" (
errSecUserCanceled-128,errSecAuthFailed-25293) becomes the statedenied. The account stays paused with the same note and a retry action, not a generic sync error, until a read succeeds. A missing item staysmissing("renew token" in the settings). - A locked login keychain also yields -25308 and is handled the same way.
- Logs carry the operation, account id and state only, never the token (
keychain_access,keychain_unlockaudit event). Error texts are the fixed state texts. - State mapping tests:
secrets.rs(status_codes_map_to_keychain_states,background_read_refusal_needs_approval_not_denied,token_state_of_read_results) andaccounts.rs(approval, denial, missing).
Background services read the token without a prompt (#369)#
The classifier and dispatcher run the stable per-user CLI copy (cli_install::stable_path()), not
the app. On macOS the keychain access list is per binary, so the app being allowed says nothing
about the services: a service that would need a prompt cannot answer it and stops reading.
- State per account (
ServiceTokenAccess, JSON camelCase):readable(silent read works),needsPrompt(token stored, a prompt or refusal would block the service),missing(no token),unsupported(store build, no services) andfailed(keychain error, unknown). - Detection asks the service's own binary:
gitoodo token-access --account <id>reads through the same store the services use (ServiceEnvStoreoverKeyringStore) with user interaction switched off and prints one state word, never a token. The mapping is the pure functionServiceTokenAccess::of; a failed or unparsable run counts asfailed, neverreadable. - Fix:
gitoodo token-access --account <id> --grantreads with the prompt allowed. The user chooses "Always Allow" once and the CLI copy reads silently afterwards. The grant survives later builds only with a stable signing identity (Developer ID, #364); ad-hoc signatures change the code hash and the prompt returns after an update, so the status showsneedsPromptagain. - Automatic grant (#594): the app runs that grant itself, without a user step, for every
account in
needsPromptafter a token is stored or renewed, after the service CLI is installed and once at launch. With a Developer ID build the app owns the item and the CLI copy carries the same team, so no dialog appears and the item's partition list gainsteamid:<team>; the registered services are restarted to pick it up (audit eventservice_token_auto_grant). The manual "Allow access" in the status view stays as the fallback for a declined or ad-hoc build. - Windows Credential Manager has no access list, so the state there is
readableormissing. - Tauri:
service_token_access(id)andservice_token_grant(id)return the state;setup_statuscarriestokenAccess: [{ account, access }]for all accounts (empty while the CLI copy is not installed). The grant writes the audit eventservice_token_grant. - Tests:
secrets.rs(service_access_*),service_access.rs(output mapping),main.rs(commands_and_flags_parse).
Windows: Credential Manager (CredRead/CredWrite) has no per-app access list and no consent
dialog; any process of the signed-in user reads the credential. There is nothing to announce or
deny, so the keychain states never occur on Windows (Microsoft Learn, CredReadW, "Credentials
Management"). Not run on a Windows host.
Reduced Tauri capabilities#
src-tauri/capabilities/default.json grants only core:event:allow-listen, core:event:allow-unlisten
and core:app:allow-version. The frontend uses invoke (always allowed for app commands), event
listening and the app version; everything else (network, keychain, files, dialogs, opener, autostart)
runs in Rust.
Sources#
Not machine-verified: the Apple Developer pages are client-rendered and could not be fetched as text, so statements based on them (entitlement names, usage-description keys, Settings URLs) come from the documentation as known and from the Tauri/Apple tooling, and must be confirmed in review.
- Apple HIG, Privacy: https://developer.apple.com/design/human-interface-guidelines/privacy
- Apple, App Sandbox entitlements and
NSLocalNetworkUsageDescription: https://developer.apple.com/documentation/bundleresources/information-property-list/nslocalnetworkusagedescription - Apple, security-scoped bookmarks: https://developer.apple.com/documentation/foundation/nsurl/bookmark-creation-options
- Apple,
SMAppService: https://developer.apple.com/documentation/servicemanagement/smappservice - Microsoft Learn, app capability declarations: https://learn.microsoft.com/windows/uwp/packaging/app-capability-declarations
- Microsoft Learn,
windows.startupTask: https://learn.microsoft.com/uwp/schemas/appxpackage/uapmanifestschema/element-uap5-startuptask - Apple TN3137, On Mac keychain APIs and implementations: https://developer.apple.com/documentation/technotes/tn3137-on-mac-keychains
- Apple, Sharing access to keychain items among a collection of apps: https://developer.apple.com/documentation/security/sharing-access-to-keychain-items-among-a-collection-of-apps
- Apple TN3125, Inside Code Signing: Provisioning Profiles: https://developer.apple.com/documentation/technotes/tn3125-inside-code-signing-provisioning-profiles
- Apple,
kSecUseDataProtectionKeychain(alsoerrSecMissingEntitlement-34018 inSecBase.h): https://developer.apple.com/documentation/security/ksecusedataprotectionkeychain - Apple, Code Signing Guide, designated requirements: https://developer.apple.com/library/archive/documentation/Security/Conceptual/CodeSigningGuide/RequirementLang/RequirementLang.html
- Apple TN2206, macOS Code Signing In Depth: https://developer.apple.com/library/archive/technotes/tn2206/_index.html
- Apple Platform Security, Keychain data protection: https://support.apple.com/guide/security/keychain-data-protection-secb0694df1a/web
- Apple Support, Restore your Mac from a backup (Time Machine): https://support.apple.com/en-us/102307
- Apple Support, Transfer to a new Mac with Migration Assistant: https://support.apple.com/en-us/102613
- Apple, Developer ID (certificate renewal keeps the team): https://developer.apple.com/developer-id/
- Apple,
SecKeychainSetUserInteractionAllowed: https://developer.apple.com/documentation/security/1393270-seckeychainsetuserinteractionall - Microsoft Learn, Credential Manager /
CredRead: https://learn.microsoft.com/windows/win32/api/wincred/nf-wincred-credreadw - Microsoft Learn, Credentials Management: https://learn.microsoft.com/windows/win32/secauthn/credentials-management
- Microsoft Learn, launch Settings with
ms-settings:: https://learn.microsoft.com/windows/apps/develop/launch/launch-settings-app
Verified and open#
Verified on the Mac: plist lint (plutil -lint), Rust and frontend unit tests for the state-to-behaviour
mapping, clippy, typecheck, lint.
The keychain sources TN3137, TN3125, "Sharing access to keychain items" and
kSecUseDataProtectionKeychain were fetched as text through the Apple documentation JSON. The
non-interactive read was run against the real keychain under a test service
(keyring_roundtrip, ignored by default).
Two consecutively signed builds (2026-11-09, Darwin 27): a probe binary on crates/core
(KeyringStore, own test service) was built three times with a code change in between, each with a
new cdhash, and signed with the Developer ID certificate, hardened runtime and a fixed identifier.
Build 1 stored the item; builds 2 and 3 read it in the background without a dialog (available).
The same code signed ad hoc read accessNeeded without a dialog (raw status -25293, see above).
The test item was deleted afterwards.
Open:
- Keychain (#126): the cross-build read without prompt, the migration of a real old item and the App Store build's keychain run (TestFlight) are unverified.
- Keychain: no real prompt or "Don't Allow" click (needs a human at the dialog), no App Store build, no restored backup; Windows Credential Manager is from the documentation only.
- Sandbox: the store build ran ad hoc signed with
Entitlements.appstore.plist(2026-11-10); notarized, TestFlight and MSIX runs did not happen. - Windows is not verified on a Windows host (test machine only).
- Agent skill folder access uses persistent security-scoped bookmarks through the scoped-folder crate. Per-target restore, stale grants and denied access still need a native store-build run.
SMAppServiceautostart (store build) and the MSIXStartupTaskare implemented (#75) but not yet exercised on a signed build.- Windows has no notification probe (
ToastNotifier.Setting); the general hint stays there. - The skill catalog reads package state within the selected folder grant; without access it reports an unavailable state. Store compilation passes, but this flow has not been exercised in a store build.
- The MSIX manifest is a template with placeholders (identity, publisher) for the Store account values.
Forge token scopes (#189)#
Gitoodo no longer reads or marks forge notifications, so the token wizard and the permission
check ask for no notification scopes. GitHub needs repo (or public_repo) and read:user;
Gitea read:user, read:repository and read:issue (plus write:issue to answer); GitLab
read_api (plus api to answer). Existing tokens that still carry notification scopes keep
working; the extra scopes are ignored.
Agent skills#
Settings → AI agents → Skills offers the bundled question-format and Computer Use
packages. Select Claude Code, Codex, or the shared Agent Skills folder before an
operation. The confirmation shows the resolved destination. Codex uses an absolute
CODEX_HOME when configured; otherwise it uses the standard home directory.
Gitoodo updates and removes only unchanged copies it manages. External, linked or
locally modified copies remain untouched. Installing the Computer Use instructions
and helper sources does not grant OS access: the POSIX controller needs Python 3.8+,
and Windows is an SSH target rather than a native controller. On macOS the agent is one
signed app, "Gitoodo Computer Use" (de.gitoodo.app.lcu-agent) in
~/Library/Application Support/lan-computer-use/, which needs Accessibility and Screen
Recording once per Mac. Release builds ship it signed with Developer ID and notarized
(scripts/build-local-mac.sh, scripts/release-mac.sh), so the grants survive skill and
app updates; without it the controller builds the agent with the Xcode Command Line Tools
and signs it with a Developer ID or the self-signed identity from cu signing-setup.
cu hello names the exact switch. Detailed requirements are available on the skill page
and in the installed reference ("Permissions (macOS)").
The skill page's permission assistant shows both switches of this Mac live: Gitoodo asks the
agent (hello over 127.0.0.1, port and token from its state.json) and starts it through
LaunchServices when it is not running, so the agent is its own responsible process. Screen
Recording is read once per process, so a check restarts an idle agent that reports it missing
(or that a terminal started); while a cu task holds it (overlay, lease_left in hello)
the assistant says the switch applies after the restart instead. "Open settings" lets the
agent list itself in exactly that pane (fallback: the pane's URL), and returning to Gitoodo
checks again. Old entries are named when the privacy database is readable or cu found them.
Other Macs show their agent's answer through cu's SSH forward while it is up, otherwise
cu hello's last report, with the command that opens the pane on that Mac. Windows targets
need no switches; the assistant lists their requirements (OpenSSH server, a signed-in
unlocked user, no control of elevated windows or UAC prompts, Smart App Control may block
the unsigned agent). The store build shows the steps without starting the agent.
The macOS store build asks for access to the selected agent folder and remembers that folder separately for each destination. Merely selecting a destination never installs a package or changes the agent's configuration.