Skip to content

graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs

Python

Allow distribution signing without optional passkey profile

Rach Pradhanda2885f18c6f
diff --git a/apps/native/electron/README.md b/apps/native/electron/README.md
index 57aa35f1..2743835e 100644
--- a/apps/native/electron/README.md
+++ b/apps/native/electron/README.md
@@ -72,20 +72,21 @@ permission UI and release updater are follow-up distribution work.
## Browser passkeys
-Developer ID signing writes the Touch ID keychain group into both the main app's
-entitlements and `Contents/Resources/webauthn.json`. Startup configures Electron
-from that signed resource before creating browser pages. The group uses the
-signing team and bundle identifier; keep both stable across releases so existing
-credentials remain accessible. If the signing identity is a certificate hash,
-set `GRAFF_SIGN_TEAM_ID` to its ten-character Apple team identifier.
-
-Signing also requires `GRAFF_WEBAUTHN_PROFILE`: a valid macOS provisioning profile
-for that signing certificate/team and bundle identifier, authorizing the
-`keychain-access-groups` value (an authorized team wildcard is also accepted).
-The signer checks its platform, expiration, app identifier and group, then embeds
-it and supplies the matching `com.apple.application-identifier`. A bare keychain
-entitlement without an authorizing profile can pass signature verification but
-be rejected by macOS at launch. Do not omit this provisioning step.
+Touch ID passkeys are optional in Developer ID distributions. Set
+`GRAFF_WEBAUTHN_PROFILE` to enable them: the signer validates the macOS profile
+for the signing team and actual bundle identifier, then embeds it and adds the
+authorized application identifier and keychain group to the main app. It also
+writes the group to signed `Contents/Resources/webauthn.json`, which configures
+Electron before browser creation. Keep the team and bundle identifier stable
+across releases so existing device credentials remain accessible. If the
+signing identity is a certificate hash, set `GRAFF_SIGN_TEAM_ID` to its
+ten-character Apple team identifier.
+
+Without `GRAFF_WEBAUTHN_PROFILE`, the signer removes any stale embedded profile
+and passkey resource and omits their restricted entitlements. The app can still
+be signed and notarized, but in-app Touch ID passkeys are unavailable. A
+provided profile must authorize the group (a team wildcard is accepted); an
+invalid one fails signing rather than falling back to this mode.
On supported Macs, this enables device-bound Touch ID credentials created in
Codegraff's persistent browser partition. It does **not** expose existing iCloud
@@ -204,18 +205,20 @@ See [repeatable performance scenarios](VISUAL-TESTS.md) for the model-free runne
## Building a distribution disk image
`build.sh` produces a development app with a local signature. For public downloads,
-run `distribute.sh` with a Developer ID Application identity, an authorizing
-macOS provisioning profile (see Browser passkeys above), and a `notarytool`
-keychain profile. Bun installs the pinned Electron signing utility with the other
-development dependencies.
+run `distribute.sh` with a Developer ID Application identity and a `notarytool`
+keychain profile. Add `GRAFF_WEBAUTHN_PROFILE` only when enabling in-app Touch ID
+passkeys (see Browser passkeys above). Bun installs the pinned Electron signing
+utility with the other development dependencies.
```sh
GRAFF_SIGN_IDENTITY="Developer ID Application: Your Name (TEAMID)" \
GRAFF_NOTARY_PROFILE="notary-local" \
-GRAFF_WEBAUTHN_PROFILE="signing/Codegraff.provisionprofile" \
bash apps/native/electron/distribute.sh zig-out/electron/Codegraff.app zig-out/distribution
```
+For a passkey-enabled build, set `GRAFF_WEBAUTHN_PROFILE` to an authorizing
+profile when running the same command.
+
The command signs nested executables, notarizes and staples the app, creates the
Finder drag-to-Applications layout, then signs, notarizes and staples the DMG.
It verifies both artifacts with Gatekeeper and writes a separate DMG checksum.
@@ -282,7 +285,6 @@ artifact. With the same signing environment used for stable releases, run:
```sh
GRAFF_SIGN_IDENTITY="Developer ID Application: Your Name (TEAMID)" \
GRAFF_NOTARY_PROFILE="notary-local" \
-GRAFF_WEBAUTHN_PROFILE="signing/Codegraff.provisionprofile" \
bash apps/native/electron/distribute.sh Codegraff.app zig-out/beta-distribution
bash apps/native/electron/publish-beta-macos.sh vVERSION-beta.RUN.ATTEMPT zig-out/beta-distribution
```
diff --git a/apps/native/electron/distribute.sh b/apps/native/electron/distribute.sh
index 4c5d9646..48baed21 100755
--- a/apps/native/electron/distribute.sh
+++ b/apps/native/electron/distribute.sh
@@ -4,7 +4,6 @@ set -euo pipefail
here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
: "${GRAFF_SIGN_IDENTITY:?Set a Developer ID Application identity}"
: "${GRAFF_NOTARY_PROFILE:?Set a notarytool keychain profile}"
-: "${GRAFF_WEBAUTHN_PROFILE:?Set a macOS provisioning profile authorizing the app and WebAuthn keychain group}"
source_app="${1:?Usage: distribute.sh /path/Codegraff.app /path/output}"
out="${2:?Provide a new output directory}"
mkdir -p "$out"
diff --git a/apps/native/electron/webauthn-signing.cjs b/apps/native/electron/webauthn-signing.cjs
index 2c8558f7..d51490c8 100644
--- a/apps/native/electron/webauthn-signing.cjs
+++ b/apps/native/electron/webauthn-signing.cjs
@@ -27,7 +27,12 @@ function optionsForFile(app, config, applicationEntitlements = {}) {
const entitlements = {};
if (jit) entitlements['com.apple.security.cs.allow-jit'] = true;
if (bun) entitlements['com.apple.security.cs.allow-unsigned-executable-memory'] = true;
- if (main) Object.assign(entitlements, applicationEntitlements, { 'keychain-access-groups': [config.keychainAccessGroup] });
+ if (main) {
+ Object.assign(entitlements, applicationEntitlements);
+ if (applicationEntitlements['com.apple.application-identifier']) {
+ entitlements['keychain-access-groups'] = [config.keychainAccessGroup];
+ }
+ }
return { hardenedRuntime: true, entitlements };
};
}
@@ -56,7 +61,10 @@ async function signBundle({ app, identity, teamId, profilePath, sign, readProvis
if (!app || !identity) throw new Error('Provide an app path and GRAFF_SIGN_IDENTITY.');
app = path.resolve(app);
const config = signingConfig(identity, teamId, readBundleId(app));
- const applicationEntitlements = profileEntitlements(readProvisioningProfile(profilePath), config);
+ // A profile is needed only for the optional Touch ID keychain group. If one
+ // was supplied, validate it strictly rather than silently signing without it.
+ const applicationEntitlements = profilePath
+ ? profileEntitlements(readProvisioningProfile(profilePath), config) : {};
const fileOptions = optionsForFile(app, config, applicationEntitlements);
const temporary = await fs.mkdtemp(path.join(os.tmpdir(), 'graff-sign-entitlements-'));
try {
@@ -71,13 +79,21 @@ async function signBundle({ app, identity, teamId, profilePath, sign, readProvis
paths.set(key, plistPath);
}
}
- // osx-sign's automatic embedding keeps stale profiles; replace with the one validated above.
- await fs.copyFile(profilePath, path.join(app, 'Contents', 'embedded.provisionprofile'));
- await fs.writeFile(path.join(app, 'Contents', 'Resources', 'webauthn.json'), `${JSON.stringify(config)}\n`);
+ // The source bundle may have been signed before. Never retain its profile
+ // or passkey resource in a distribution without the matching entitlement.
+ const embedded = path.join(app, 'Contents', 'embedded.provisionprofile');
+ const resource = path.join(app, 'Contents', 'Resources', 'webauthn.json');
+ if (profilePath) {
+ await fs.copyFile(profilePath, embedded);
+ await fs.writeFile(resource, `${JSON.stringify(config)}\n`);
+ } else {
+ await fs.rm(embedded, { force: true });
+ await fs.rm(resource, { force: true });
+ }
await sign({
app, platform: 'darwin', type: 'distribution', identity,
preAutoEntitlements: false, preEmbedProvisioningProfile: false,
- provisioningProfile: path.resolve(profilePath),
+ ...(profilePath ? { provisioningProfile: path.resolve(profilePath) } : {}),
optionsForFile(file) {
const options = fileOptions(file);
return { ...options, entitlements: paths.get(JSON.stringify(options.entitlements)) };
diff --git a/apps/native/electron/webauthn-signing.test.cjs b/apps/native/electron/webauthn-signing.test.cjs
index 688dccd9..c83a1b6a 100644
--- a/apps/native/electron/webauthn-signing.test.cjs
+++ b/apps/native/electron/webauthn-signing.test.cjs
@@ -27,14 +27,14 @@ test('team derives only from an anchored Developer ID Application identity or ex
}
});
-test('only main app gets keychain access; existing JIT and Bun policies stay exact', () => {
+test('profile-gated entitlements stay on the main app; JIT and Bun policies stay exact', () => {
const app = path.resolve('Fixture.app');
const config = signingConfig(identity, undefined, bundleId);
- const options = optionsForFile(app, config);
+ const options = optionsForFile(app, config, { 'com.apple.application-identifier': `ABCDE12345.${bundleId}` });
const jit = { 'com.apple.security.cs.allow-jit': true };
const cases = [
- [app, { ...jit, 'keychain-access-groups': [config.keychainAccessGroup] }],
- [app + '/', { ...jit, 'keychain-access-groups': [config.keychainAccessGroup] }],
+ [app, { ...jit, 'com.apple.application-identifier': `ABCDE12345.${bundleId}`, 'keychain-access-groups': [config.keychainAccessGroup] }],
+ [app + '/', { ...jit, 'com.apple.application-identifier': `ABCDE12345.${bundleId}`, 'keychain-access-groups': [config.keychainAccessGroup] }],
[`${app}/Contents/Resources/bun`, { ...jit, 'com.apple.security.cs.allow-unsigned-executable-memory': true }],
[`${app}/Contents/Frameworks/Helper.app`, jit],
[`${app}/Contents/Frameworks/Electron Framework.framework/Versions/A/Electron Framework`, jit],
@@ -42,6 +42,40 @@ test('only main app gets keychain access; existing JIT and Bun policies stay exa
[`${app}/Contents/Frameworks/library.dylib`, {}],
];
for (const [file, entitlements] of cases) assert.deepEqual(options(file), { hardenedRuntime: true, entitlements });
+ assert.deepEqual(optionsForFile(app, config)(app), { hardenedRuntime: true, entitlements: jit });
+});
+
+test('profile-free signing removes stale passkey artifacts and restricted entitlements', async () => {
+ const root = await fs.mkdtemp(path.join(os.tmpdir(), 'webauthn-sign-plain-'));
+ const app = path.join(root, 'Fixture.app');
+ const resources = path.join(app, 'Contents', 'Resources');
+ try {
+ await fs.mkdir(resources, { recursive: true });
+ const embedded = path.join(app, 'Contents', 'embedded.provisionprofile');
+ const resource = path.join(resources, 'webauthn.json');
+ await fs.writeFile(embedded, 'stale profile');
+ await fs.writeFile(resource, '{"stale":true}');
+ let calls = 0;
+ await signBundle({ app, identity, readBundleId: () => bundleId,
+ readProvisioningProfile: () => assert.fail('must not read a profile'),
+ sign: async (options) => {
+ calls++;
+ assert.equal(options.preAutoEntitlements, false);
+ assert.equal(options.preEmbedProvisioningProfile, false);
+ assert.equal(Object.hasOwn(options, 'provisioningProfile'), false);
+ await assert.rejects(fs.access(embedded), { code: 'ENOENT' });
+ await assert.rejects(fs.access(resource), { code: 'ENOENT' });
+ for (const file of [app, `${resources}/bun`, `${app}/Contents/Frameworks/Helper.app`, `${resources}/other`]) {
+ const result = options.optionsForFile(file);
+ assert.equal(result.hardenedRuntime, true);
+ const entitlements = plist.parse(await fs.readFile(result.entitlements, 'utf8'));
+ assert.deepEqual(entitlements, optionsForFile(app, signingConfig(identity, undefined, bundleId))(file).entitlements);
+ assert.equal(Object.hasOwn(entitlements, 'com.apple.application-identifier'), false);
+ assert.equal(Object.hasOwn(entitlements, 'keychain-access-groups'), false);
+ }
+ } });
+ assert.equal(calls, 1);
+ } finally { await fs.rm(root, { recursive: true, force: true }); }
});
for (const fails of [false, true]) test(`sign dispatch writes matching config and plist entitlements, cleans temporary files (failure=${fails})`, async () => {
@@ -90,7 +124,6 @@ test('invalid metadata fails before writing config or invoking signer', async ()
let called = false;
await assert.rejects(signBundle({ app: 'Fixture.app', identity, teamId: '', readBundleId: () => bundleId, sign: () => { called = true; } }), /valid signing team/);
await assert.rejects(signBundle({ app: 'Fixture.app', identity, readBundleId: () => 'bad/bundle', sign: () => { called = true; } }), /CFBundleIdentifier/);
- await assert.rejects(signBundle({ app: 'Fixture.app', identity, readBundleId: () => bundleId, sign: () => { called = true; } }), /GRAFF_WEBAUTHN_PROFILE/);
assert.equal(called, false);
});
@@ -107,6 +140,16 @@ test('signBundle rejects a same-team profile for a different bundle before invok
assert.equal(called, false);
});
+test('an explicitly supplied unreadable profile fails before signing', async () => {
+ let called = false;
+ await assert.rejects(signBundle({
+ app: 'Fixture.app', identity, profilePath: 'missing.provisionprofile',
+ readProvisioningProfile: () => { throw Error('profile read failed'); },
+ readBundleId: () => bundleId, sign: () => { called = true; },
+ }), /profile read failed/);
+ assert.equal(called, false);
+});
+
test('default reader obtains actual bundle identifier through PlistBuddy', { skip: process.platform !== 'darwin' }, async () => {
const root = await fs.mkdtemp(path.join(os.tmpdir(), 'webauthn-plist-test-'));
const app = path.join(root, 'Fixture.app');
diff --git a/apps/native/electron/webauthn.cjs b/apps/native/electron/webauthn.cjs
index fb666293..c8096570 100644
--- a/apps/native/electron/webauthn.cjs
+++ b/apps/native/electron/webauthn.cjs
@@ -60,7 +60,7 @@ async function showPasskeyHelp({ window, browser, dialog, shell, configured }) {
} catch { /* No active web page. */ }
const { response } = await dialog.showMessageBox(window, {
type: 'info', title: 'Browser passkeys', message: 'Having trouble signing in with a passkey?',
- detail: `${configured ? 'This signed app is configured for device-bound Touch ID passkeys on supported Macs.' : 'Touch ID passkeys are not configured in this build. Use a signed distribution on a supported Mac.'} Existing iCloud Keychain passkeys are not available here. Use the site’s password or another sign-in method, or open the page in your default browser. Signing in there does not sign you in here.`,
+ detail: `${configured ? 'This signed app is configured for device-bound Touch ID passkeys on supported Macs.' : 'Touch ID passkeys are unavailable in this build.'} Existing iCloud Keychain passkeys are not available here. Use the site’s password or another sign-in method, or open the page in your default browser. Signing in there does not sign you in here.`,
buttons: url ? ['Close', 'Open page in default browser'] : ['Close'], defaultId: 0, cancelId: 0, noLink: true,
});
if (response === 1 && url && !window.isDestroyed()) await shell.openExternal(url);
diff --git a/apps/native/electron/webauthn.test.cjs b/apps/native/electron/webauthn.test.cjs
index 37b40fd0..66ef506c 100644
--- a/apps/native/electron/webauthn.test.cjs
+++ b/apps/native/electron/webauthn.test.cjs
@@ -90,7 +90,7 @@ test('fallback explains credential limitations and opens only after explicit con
dialog: { showMessageBox: async (_parent, options) => {
assert.match(options.detail, /iCloud Keychain passkeys are not available/);
assert.match(options.detail, /Signing in there does not sign you in here/);
- assert.match(options.detail, configured ? /device-bound/ : /not configured/);
+ assert.match(options.detail, configured ? /device-bound/ : /unavailable in this build/);
return { response };
} }, shell: { openExternal: async url => opened.push(url) },
});
diff --git a/docs/adr/0132-desktop-passkeys-use-signed-device-credentials.md b/docs/adr/0132-desktop-passkeys-use-signed-device-credentials.md
index 9b935196..371c88d5 100644
--- a/docs/adr/0132-desktop-passkeys-use-signed-device-credentials.md
+++ b/docs/adr/0132-desktop-passkeys-use-signed-device-credentials.md
@@ -12,18 +12,21 @@ not sufficient evidence that every stalled sign-in is fixed.
## Decision
-The distribution signer derives one credential group from the signing team and
-actual bundle identifier, puts it in the main application's keychain entitlement,
-and writes the identical value to a signed resource. Startup configures Touch ID
-from that resource before browser creation. Development builds without it leave
-the authenticator disabled rather than inventing a signing identity.
-
-The signer requires and embeds a macOS provisioning profile authorizing the
-team, application identifier, and credential group, and includes the authorized
-application identifier in the main app's entitlements. A stale embedded profile
-is replaced, not silently retained. Supplying a keychain entitlement alone can
-pass `codesign --verify` while macOS refuses launch for lack of a matching
-profile; the build must not mistake signature integrity for authorization.
+When an authorizing profile is supplied, the distribution signer derives one
+credential group from the signing team and actual bundle identifier, puts it in
+the main application's keychain entitlement, and writes the identical value to
+a signed resource. Startup configures Touch ID from that resource before browser
+creation. Builds without it leave the authenticator disabled.
+
+The profile is optional for general Developer ID signing and notarization. If
+supplied, the signer strictly validates and embeds it, and includes its
+authorized application identifier in the main app's entitlements. If omitted,
+the signer omits the profile-gated entitlements and removes any stale embedded
+profile and signed passkey resource from the copied bundle. Supplying a keychain
+entitlement alone can pass `codesign --verify` while macOS refuses launch for
+lack of a matching profile; the build must not mistake signature integrity for
+authorization. An invalid supplied profile is an error, not a reason to fall
+back to a profile-free build.
The persistent browser session handles account selection through a parented
native dialog. Only the visible owned browser page can prompt; cancellation,
@@ -38,9 +41,11 @@ third-party iCloud credentials are accessible.
## Consequences
-Signing team, bundle identifier, and browser partition must remain stable to
-retain credential access. Unsupported credentials still need another sign-in
-method. Automated virtual-authenticator checks establish request dispatch and
-selection behavior, not biometric or keychain access. Release support requires
-registration, persistence, authentication, and cancellation validation in the
-Developer ID-signed application on supported hardware.
+For passkey-enabled builds, signing team, bundle identifier, and browser
+partition must remain stable to retain credential access. Profile-free builds
+cannot use in-app Touch ID passkeys; unsupported credentials still need another
+sign-in method. Automated virtual-authenticator checks establish request
+dispatch and selection behavior, not biometric or keychain access. Passkey
+release support requires registration, persistence, authentication, and
+cancellation validation in the Developer ID-signed application on supported
+hardware.