Skip to content

Commit ee8ffde

Browse files
authored
feat(install): support custom bundle identifier in Apple ID mode (#209)
The signing engine accepts --custom-identifier together with --apple-id, but every entry point refused the combination. Worse, an Apple ID record was keyed by the bundle identifier of the IPA and the account, so installing the same IPA with and without a custom identifier collapsed into a single record and the second install overwrote the identifier of the first. Key the record by the bundle identifier actually installed on the device (COALESCE of signed_bundle_identifier, custom_identifier and bundle_identifier, so the columns AutoMigrate leaves NULL on existing rows are ignored) and pass the identifier to the engine in both signing modes. A refresh passes it again: the stored IPA still carries the original bundle identifier, so without it the app would be refreshed under another App ID. The install is thus a second app on the device, with its own record, App ID and expiry. Also keep the identifier when the MCP tool queues an Apple ID install (it validated the value but stored it only for external certificates) and add it to the install queue key, so two installs of the same IPA under different identifiers are both queued. The install page shows the field in both modes in the tooltip style of the app name field, previews the identifier of the chosen IPA, and validates it before submitting.
1 parent be67a52 commit ee8ffde

27 files changed

Lines changed: 539 additions & 77 deletions

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ atvloadly is a web service that supports sideloading app on Apple TV. It uses [I
3030
* Supports use of multiple Apple ID accounts
3131
* Supports signing with your own certificate (P12 + provisioning profile), without an Apple ID
3232
* I18n support
33+
* Supports installing an app under a custom bundle identifier (Apple ID or P12), next to the original app
3334

3435
## Screenshots
3536

‎README_cn.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@ atvloadly 是一个支持在 AppleTV 上侧载应用的 web 服务。底层通
3131
* 支持同时使用多个 Apple ID 帐号
3232
* 支持使用自有证书(P12 + 描述文件)签名,无需 Apple ID
3333
* i18n 多语言支持
34+
* 支持使用自定义 Bundle ID 安装应用(Apple ID 或 P12 均可),可与原应用共存
3435

3536
## 截图
3637

‎README_sv.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ atvloadly är en webbtjänst för sideloading av appar på Apple TV. Den använd
2929
* Stöd för att följa GitHub Releases / AltStore-källor med manuella eller automatiska appuppdateringar
3030
* Stöd för flera Apple ID-konton
3131
* Stöd för flera språk (i18n)
32+
* Stöd för att installera en app under ett anpassat paket-ID (Apple ID eller P12), bredvid den ursprungliga appen
3233

3334
## Skärmbilder
3435

‎doc/external-certificate.md‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -138,6 +138,14 @@ With an explicit App ID profile the application identifier stays the profile
138138
App ID; with a wildcard profile it follows the new bundle identifiers. The
139139
custom identifier is stored with the app and reused by reinstalls.
140140

141+
The custom identifier is available in both signing modes. It changes the app on
142+
the device, so installing the same IPA with and without it puts **two different
143+
apps** on the device and creates two records: an Apple ID install under a custom
144+
identifier registers a second App ID (and therefore consumes another slot of the
145+
account's App ID quota), and a refresh re-signs the app under the identifier
146+
recorded with it. The two records are keyed by the identifier the app is
147+
installed under, so they refresh, expire and reinstall independently.
148+
141149
**Remove extensions** (optional): removes every app extension before signing.
142150
Extensions are never removed unless you enable it; the plan lists the removed
143151
extensions.
@@ -331,7 +339,8 @@ directory; its `path` is passed as `ipa_path` to the check and to the install
331339
message. Its failures have `data: null`.
332340

333341
`custom_identifier` is optional (empty keeps the bundle identifiers of the IPA)
334-
and only accepted with `signing_mode=external_certificate`. The same fields are
342+
and accepted with either signing mode; it is validated before the install is
343+
queued. The same fields are
335344
accepted in the install message of the `/ws/install` WebSocket (`signing_mode`,
336345
`signing_identity_id`, `remove_extensions`, `allow_missing_entitlements`,
337346
`custom_identifier`) and, except `allow_missing_entitlements`, by the MCP

‎internal/manager/install_manager.go‎

Lines changed: 19 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -51,12 +51,16 @@ type InstallManager struct {
5151
}
5252

5353
type InstallOptions struct {
54-
UDID string
55-
IP string
56-
Port uint16
57-
Account string
58-
IpaPath string
59-
CustomName string
54+
UDID string
55+
IP string
56+
Port uint16
57+
Account string
58+
IpaPath string
59+
CustomName string
60+
// CustomIdentifier is the main bundle identifier the app is installed
61+
// under, in both signing modes; empty keeps the bundle identifiers of the
62+
// IPA. The app is a different app on the device for each identifier.
63+
CustomIdentifier string
6064
RemoveExtensions bool
6165
RefreshMode bool
6266
// SigningMode selects how the app is signed; empty means SigningModeAppleID.
@@ -249,6 +253,15 @@ func buildInstallArgs(opts InstallOptions, provisionPath string) []string {
249253
args = append(args, "--custom-name", opts.CustomName)
250254
}
251255

256+
// Installs the app under another bundle identifier, which registers a
257+
// second App ID: the app on the device is then a different app from the one
258+
// installed under the bundle identifier of the IPA. The value is attached
259+
// to its flag because clap reads a separate value starting with '-' as a
260+
// flag (see buildExternalInstallArgs).
261+
if opts.CustomIdentifier != "" {
262+
args = append(args, "--custom-identifier="+opts.CustomIdentifier)
263+
}
264+
252265
// The engine revokes nothing unless handed this one-shot authorization,
253266
// which the install page gives only after the user picked a certificate.
254267
if opts.RevokeCertificateSerial != "" {
Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
package manager
2+
3+
import (
4+
"context"
5+
"os"
6+
"path/filepath"
7+
"strings"
8+
"testing"
9+
10+
"github.com/bitxeno/atvloadly/internal/app"
11+
"github.com/bitxeno/atvloadly/internal/model"
12+
)
13+
14+
// fakeAppleIDEngine puts a plumesign on PATH that records the arguments of the
15+
// sign command it is given and reports a successful installation. Every other
16+
// subcommand (check afc, device-info) succeeds with no output.
17+
func fakeAppleIDEngine(t *testing.T) string {
18+
t.Helper()
19+
dir := t.TempDir()
20+
record := filepath.Join(dir, "args")
21+
script := "#!/bin/sh\n" +
22+
"if [ \"$1\" = sign ] || [ \"$1\" = sign-rsd ]; then\n" +
23+
" printf '%s\\n' \"$@\" > " + record + "\n" +
24+
" echo 'Installation Succeeded'\n" +
25+
"elif [ \"$1\" = check ]; then\n" +
26+
" echo 'SUCCESS'\n" +
27+
"fi\n" +
28+
"exit 0\n"
29+
if err := os.WriteFile(filepath.Join(dir, "plumesign"), []byte(script), 0o755); err != nil {
30+
t.Fatal(err)
31+
}
32+
t.Setenv("PATH", dir+string(os.PathListSeparator)+os.Getenv("PATH"))
33+
return record
34+
}
35+
36+
// setupAppleIDInstall prepares the configuration and the device registry an
37+
// Apple ID installation reads.
38+
func setupAppleIDInstall(t *testing.T, udid string) {
39+
t.Helper()
40+
previousConfig, previousSettings := app.Config, app.Settings
41+
app.Config = &app.Configuration{}
42+
app.Config.Server.DataDir = t.TempDir()
43+
app.Settings = &app.SettingsConfiguration{}
44+
t.Cleanup(func() { app.Config, app.Settings = previousConfig, previousSettings })
45+
46+
deviceManager.devices.Store(udid, model.Device{UDID: udid, Name: "Apple TV", DeviceClass: "AppleTV"})
47+
t.Cleanup(func() { deviceManager.devices.Delete(udid) })
48+
}
49+
50+
// An Apple ID installation passes the custom bundle identifier to the engine,
51+
// and a refresh passes it again: the stored IPA still carries the bundle
52+
// identifier of the original package, so without it the app would be refreshed
53+
// under another App ID.
54+
func TestStartAppleIDPassesCustomIdentifier(t *testing.T) {
55+
const udid = "TEST-DEVICE-UDID"
56+
for _, tt := range []struct {
57+
name string
58+
refresh bool
59+
custom string
60+
wantFlag string
61+
wantRefresh bool
62+
}{
63+
{name: "install with custom identifier", custom: "app.custom", wantFlag: "--custom-identifier=app.custom"},
64+
{name: "refresh with custom identifier", custom: "app.custom", refresh: true, wantFlag: "--custom-identifier=app.custom", wantRefresh: true},
65+
{name: "install without custom identifier"},
66+
} {
67+
t.Run(tt.name, func(t *testing.T) {
68+
record := fakeAppleIDEngine(t)
69+
setupAppleIDInstall(t, udid)
70+
71+
mgr := NewInstallManager()
72+
defer mgr.Close()
73+
74+
err := mgr.Start(context.Background(), InstallOptions{
75+
UDID: udid,
76+
Account: "user@example.com",
77+
IpaPath: "app.ipa",
78+
CustomIdentifier: tt.custom,
79+
RefreshMode: tt.refresh,
80+
})
81+
if err != nil {
82+
t.Fatalf("install failed: %v", err)
83+
}
84+
85+
data, err := os.ReadFile(record)
86+
if err != nil {
87+
t.Fatalf("the signing engine was not run: %v", err)
88+
}
89+
args := strings.Split(strings.TrimRight(string(data), "\n"), "\n")
90+
joined := strings.Join(args, " ")
91+
92+
if tt.wantFlag == "" {
93+
if strings.Contains(joined, "--custom-identifier") {
94+
t.Fatalf("no custom identifier was requested but the engine got %q", joined)
95+
}
96+
} else if !containsArg(args, tt.wantFlag) {
97+
t.Fatalf("engine args %q do not contain %q", joined, tt.wantFlag)
98+
}
99+
if gotRefresh := containsArg(args, "--refresh"); gotRefresh != tt.wantRefresh {
100+
t.Fatalf("--refresh present = %v, want %v (%q)", gotRefresh, tt.wantRefresh, joined)
101+
}
102+
})
103+
}
104+
}
105+
106+
func containsArg(args []string, want string) bool {
107+
for _, a := range args {
108+
if a == want {
109+
return true
110+
}
111+
}
112+
return false
113+
}

‎internal/manager/install_manager_test.go‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,27 @@ func TestBuildInstallArgsAppleID(t *testing.T) {
4444
opts: InstallOptions{UDID: "DEVICE", IP: "192.0.2.10", Port: 49152, Account: "user@example.com", IpaPath: "app.ipa", CustomName: "My App", SigningMode: model.SigningModeAppleID},
4545
want: []string{"sign-rsd", "--apple-id", "--register-and-install", "--output-provision", "embedded.mobileprovision", "--ip", "192.0.2.10", "--port", "49152", "--udid", "DEVICE", "-u", "user@example.com", "-p", "app.ipa", "--custom-name", "My App"},
4646
},
47+
{
48+
name: "lockdown with custom identifier",
49+
opts: InstallOptions{UDID: "DEVICE", Account: "user@example.com", IpaPath: "app.ipa", CustomIdentifier: "app.custom"},
50+
want: []string{"sign", "--apple-id", "--register-and-install", "--output-provision", "embedded.mobileprovision", "--udid", "DEVICE", "-u", "user@example.com", "-p", "app.ipa", "--custom-identifier=app.custom"},
51+
},
52+
{
53+
// A refresh re-signs the stored IPA, which still carries the bundle
54+
// identifier of the original package: the custom identifier must be
55+
// passed again or the app would be refreshed under another App ID.
56+
// --refresh itself is appended by startAppleID, not here.
57+
name: "refresh with custom identifier",
58+
opts: InstallOptions{UDID: "DEVICE", Account: "user@example.com", IpaPath: "app.ipa", CustomIdentifier: "app.custom", RefreshMode: true},
59+
want: []string{"sign", "--apple-id", "--register-and-install", "--output-provision", "embedded.mobileprovision", "--udid", "DEVICE", "-u", "user@example.com", "-p", "app.ipa", "--custom-identifier=app.custom"},
60+
},
61+
{
62+
// clap reads a separate value starting with '-' as a flag, so the
63+
// value is always attached to its flag.
64+
name: "custom identifier with a leading hyphen",
65+
opts: InstallOptions{UDID: "DEVICE", Account: "user@example.com", IpaPath: "app.ipa", CustomIdentifier: "-beta.example.app"},
66+
want: []string{"sign", "--apple-id", "--register-and-install", "--output-provision", "embedded.mobileprovision", "--udid", "DEVICE", "-u", "user@example.com", "-p", "app.ipa", "--custom-identifier=-beta.example.app"},
67+
},
4768
}
4869
for _, tt := range tests {
4970
t.Run(tt.name, func(t *testing.T) {

‎internal/mcp/tools/get_app_list.go‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,11 @@ type appListItem struct {
2626
ExpirationDate *time.Time `json:"expiration_date,omitempty"`
2727
IsExpired bool `json:"is_expired"`
2828
SigningMode model.SigningMode `json:"signing_mode"`
29+
// CustomIdentifier is the bundle identifier the app is installed under when
30+
// the user requested one; empty keeps the bundle identifier of the IPA. Two
31+
// records can share BundleIdentifier and differ only by this value: they
32+
// are two different apps on the device.
33+
CustomIdentifier string `json:"custom_identifier,omitempty"`
2934
// SigningIdentityID is the external signing identity of the app.
3035
SigningIdentityID uint `json:"signing_identity_id,omitempty"`
3136
// AutoRefresh reports whether the scheduled refresh renews the app; apps
@@ -87,6 +92,7 @@ func toAppListItem(app model.InstalledApp) appListItem {
8792
ExpirationDate: app.ExpirationDate,
8893
IsExpired: app.IsExpired(),
8994
SigningMode: app.EffectiveSigningMode(),
95+
CustomIdentifier: app.CustomIdentifier,
9096
SigningIdentityID: app.SigningIdentityID,
9197
AutoRefresh: !app.IsExternalSigning(),
9298
}

‎internal/mcp/tools/get_refresh_status.go‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,10 @@ type getRefreshStatusItem struct {
2525
LastErrorCode model.RefreshedError `json:"last_error_code"`
2626
IsExpired bool `json:"is_expired"`
2727
SigningMode model.SigningMode `json:"signing_mode"`
28+
// CustomIdentifier is the bundle identifier the app is installed under when
29+
// the user requested one; empty keeps the bundle identifier of the IPA. Two
30+
// records can share BundleIdentifier and differ only by this value.
31+
CustomIdentifier string `json:"custom_identifier,omitempty"`
2832
// AutoRefresh is false for apps signed with an external certificate: they
2933
// are never refreshed automatically and expire with their signing identity.
3034
AutoRefresh bool `json:"auto_refresh"`
@@ -69,6 +73,7 @@ func handleGetRefreshStatus(_ context.Context, _ *sdkmcp.CallToolRequest, input
6973
AppID: app.ID,
7074
IpaName: app.IpaName,
7175
BundleIdentifier: app.BundleIdentifier,
76+
CustomIdentifier: app.CustomIdentifier,
7277
RefreshState: state,
7378
RefreshInProgress: inProgress,
7479
LastRefreshAt: app.RefreshedDate,

‎internal/mcp/tools/install.go‎

Lines changed: 20 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ type installAppInput struct {
2525
AccountID string `json:"account_id,omitempty" jsonschema:"Optional Apple account ID (md5 of account email). Omit when signing_identity_id is set"`
2626
SigningIdentityID uint `json:"signing_identity_id,omitempty" jsonschema:"Optional imported signing identity ID: signs with that external certificate and provisioning profile instead of an Apple account. Omit account_id when set"`
2727
RemoveExtensions bool `json:"remove_extensions,omitempty" jsonschema:"Optional remove app extensions while installing"`
28-
CustomIdentifier string `json:"custom_identifier,omitempty" jsonschema:"Optional bundle identifier to install the app under, only with signing_identity_id. The IPA main bundle identifier is replaced by it in the app and its extensions. Omit to keep the IPA bundle identifiers"`
28+
CustomIdentifier string `json:"custom_identifier,omitempty" jsonschema:"Optional bundle identifier to install the app under, with either signing method. The IPA main bundle identifier is replaced by it in the app and its extensions. Omit to keep the IPA bundle identifiers. Installing the same IPA with and without it puts two different apps on the device and creates two records"`
2929
}
3030

3131
type installDeviceOption struct {
@@ -77,7 +77,8 @@ func registerInstallApp(server *sdkmcp.Server) {
7777
"If device_id or the signing choice is omitted, this tool returns options for interactive selection. " +
7878
"Ensure the user has confirmed the device and the account or signing identity before proceeding. " +
7979
"Apps signed with an external certificate are not refreshed automatically and expire with their signing identity. " +
80-
"They keep the IPA bundle identifiers unless custom_identifier is set; the provisioning profile decides their application identifier. " +
80+
"Either signing method keeps the IPA bundle identifiers unless custom_identifier is set; with an external certificate the provisioning profile decides the application identifier. " +
81+
"Installing the same IPA with and without custom_identifier installs two different apps on the device. " +
8182
"After app install task is queued, call get_install_status to track progress.",
8283
}, handleInstallApp)
8384
}
@@ -96,9 +97,6 @@ func handleInstallApp(_ context.Context, _ *sdkmcp.CallToolRequest, input instal
9697
}
9798
customIdentifier := strings.TrimSpace(input.CustomIdentifier)
9899
if customIdentifier != "" {
99-
if input.SigningIdentityID == 0 {
100-
return nil, installAppOutput{}, fmt.Errorf("custom_identifier requires signing_identity_id")
101-
}
102100
// The installation is queued: an invalid identifier is refused now.
103101
if err := appcheck.ValidateBundleIdentifier(customIdentifier); err != nil {
104102
return nil, installAppOutput{}, signingToolError(err)
@@ -117,15 +115,7 @@ func handleInstallApp(_ context.Context, _ *sdkmcp.CallToolRequest, input instal
117115
}, nil
118116
}
119117

120-
appModel := model.InstalledApp{
121-
IpaName: ipaFileNameFromURL(ipaURL),
122-
IpaPath: ipaURL,
123-
Device: selectedDevice.Name,
124-
DeviceClass: selectedDevice.DeviceClass,
125-
UDID: selectedDevice.UDID,
126-
Enabled: true,
127-
RemoveExtensions: input.RemoveExtensions,
128-
}
118+
appModel := newInstallRecord(input, *selectedDevice, customIdentifier)
129119
output := installAppOutput{
130120
Status: "installing",
131121
Message: "Install task queued to task.StartInstallApps.",
@@ -140,7 +130,6 @@ func handleInstallApp(_ context.Context, _ *sdkmcp.CallToolRequest, input instal
140130
selected := toInstallSigningIdentityOption(*identity, time.Now())
141131
appModel.SigningMode = model.SigningModeExternalCertificate
142132
appModel.SigningIdentityID = identity.ID
143-
appModel.CustomIdentifier = customIdentifier
144133
output.SelectedSigningIdentity = &selected
145134
} else {
146135
if accountID == "" {
@@ -185,6 +174,22 @@ func handleInstallApp(_ context.Context, _ *sdkmcp.CallToolRequest, input instal
185174
return nil, output, nil
186175
}
187176

177+
// newInstallRecord builds the installed app record queued for device. The
178+
// signing mode and identity are filled in by the caller; the custom identifier
179+
// applies to either signing method, so it is recorded here for both.
180+
func newInstallRecord(input installAppInput, device installDeviceOption, customIdentifier string) model.InstalledApp {
181+
return model.InstalledApp{
182+
IpaName: ipaFileNameFromURL(strings.TrimSpace(input.IpaURL)),
183+
IpaPath: strings.TrimSpace(input.IpaURL),
184+
Device: device.Name,
185+
DeviceClass: device.DeviceClass,
186+
UDID: device.UDID,
187+
Enabled: true,
188+
RemoveExtensions: input.RemoveExtensions,
189+
CustomIdentifier: customIdentifier,
190+
}
191+
}
192+
188193
// signingToolError returns the tool error of err, prefixed with its stable
189194
// signing code when it comes from the external signing pipeline.
190195
func signingToolError(err error) error {

0 commit comments

Comments
 (0)
⌂ 换网址