Integrate verified installation flow (T-302)
This commit is contained in:
@@ -0,0 +1,233 @@
|
||||
package install
|
||||
|
||||
import (
|
||||
"errors"
|
||||
"fmt"
|
||||
"path/filepath"
|
||||
|
||||
"softbox.local/core/catalog"
|
||||
"softbox.local/core/installer"
|
||||
"softbox.local/core/storage"
|
||||
)
|
||||
|
||||
var (
|
||||
ErrInstallServiceConfig = errors.New("invalid install service configuration")
|
||||
ErrInstallRequestInvalid = errors.New("invalid install request")
|
||||
ErrInstallRecordWrite = errors.New("write installed app record")
|
||||
)
|
||||
|
||||
// InstallStage makes the security-sensitive installation path observable to a
|
||||
// background caller without giving the Gio layout any filesystem work.
|
||||
type InstallStage string
|
||||
|
||||
const (
|
||||
InstallStageVerify InstallStage = "verify"
|
||||
InstallStageManifest InstallStage = "manifest"
|
||||
InstallStageExtract InstallStage = "extract"
|
||||
InstallStageRecover InstallStage = "recover"
|
||||
InstallStageSwitch InstallStage = "switch"
|
||||
InstallStageHealth InstallStage = "health"
|
||||
InstallStageRecord InstallStage = "record"
|
||||
InstallStageRollback InstallStage = "rollback"
|
||||
)
|
||||
|
||||
// InstallError preserves a stable stage and its underlying cause.
|
||||
type InstallError struct {
|
||||
Stage InstallStage
|
||||
Err error
|
||||
}
|
||||
|
||||
func (err *InstallError) Error() string {
|
||||
return fmt.Sprintf("install %s: %v", err.Stage, err.Err)
|
||||
}
|
||||
|
||||
func (err *InstallError) Unwrap() error {
|
||||
return err.Err
|
||||
}
|
||||
|
||||
// InstallRecordStore provides the app-root and installed-app record boundary
|
||||
// needed by an installation transaction.
|
||||
type InstallRecordStore interface {
|
||||
EnsureAppRoot(appID string) (string, error)
|
||||
Write(record storage.InstalledApp) error
|
||||
}
|
||||
|
||||
// InstallRequest joins an untrusted completed download with the trusted
|
||||
// Catalog selection that describes it.
|
||||
type InstallRequest struct {
|
||||
Entry catalog.Entry
|
||||
Architecture catalog.Architecture
|
||||
DownloadPath string
|
||||
}
|
||||
|
||||
// InstallResult describes an installed version after the switch commits.
|
||||
type InstallResult struct {
|
||||
AppID string
|
||||
Version string
|
||||
EntrypointPath string
|
||||
Recovery installer.RecoveryResult
|
||||
}
|
||||
|
||||
// InstallService implements the core-only verified package installation use
|
||||
// case. The caller must supply entries produced by catalog.Client.
|
||||
type InstallService struct {
|
||||
extractor installer.Extractor
|
||||
records InstallRecordStore
|
||||
health installer.HealthCheck
|
||||
}
|
||||
|
||||
func NewInstallService(
|
||||
extractor installer.Extractor,
|
||||
records InstallRecordStore,
|
||||
health installer.HealthCheck,
|
||||
) (*InstallService, error) {
|
||||
if records == nil {
|
||||
return nil, fmt.Errorf("%w: record store is required", ErrInstallServiceConfig)
|
||||
}
|
||||
if health == nil {
|
||||
return nil, fmt.Errorf("%w: %w", ErrInstallServiceConfig, installer.ErrHealthCheckRequired)
|
||||
}
|
||||
return &InstallService{
|
||||
extractor: extractor,
|
||||
records: records,
|
||||
health: health,
|
||||
}, nil
|
||||
}
|
||||
|
||||
// Install verifies and extracts one completed download, then atomically
|
||||
// switches staging into current. Metadata is written inside the Switcher
|
||||
// health phase so a write failure follows the same rollback path as health.
|
||||
func (service *InstallService) Install(request InstallRequest) (InstallResult, error) {
|
||||
expectation, record, err := resolveInstallRequest(request)
|
||||
if err != nil {
|
||||
return InstallResult{}, installError(InstallStageVerify, err)
|
||||
}
|
||||
|
||||
appRoot, err := service.records.EnsureAppRoot(record.ID)
|
||||
if err != nil {
|
||||
return InstallResult{}, installError(InstallStageRecover, err)
|
||||
}
|
||||
recovery, err := installer.Recover(appRoot)
|
||||
if err != nil {
|
||||
return InstallResult{}, installError(InstallStageRecover, err)
|
||||
}
|
||||
|
||||
extracted, err := service.extractor.ExtractVerifiedFile(
|
||||
request.DownloadPath,
|
||||
filepath.Join(appRoot, "staging"),
|
||||
expectation,
|
||||
)
|
||||
if err != nil {
|
||||
return InstallResult{}, installError(stageForPackageError(err), err)
|
||||
}
|
||||
record.Files = make([]storage.InstalledFile, 0, len(extracted.PayloadFiles))
|
||||
for _, file := range extracted.PayloadFiles {
|
||||
record.Files = append(record.Files, storage.InstalledFile{
|
||||
Path: file.Path,
|
||||
Size: file.Size,
|
||||
SHA256: file.SHA256,
|
||||
})
|
||||
}
|
||||
|
||||
var recordWriteErr error
|
||||
switcher := installer.NewSwitcher(func(currentPath string) error {
|
||||
if err := service.health(currentPath); err != nil {
|
||||
return err
|
||||
}
|
||||
if err := service.records.Write(record); err != nil {
|
||||
recordWriteErr = err
|
||||
return fmt.Errorf("%w: %w", ErrInstallRecordWrite, err)
|
||||
}
|
||||
return nil
|
||||
})
|
||||
if err := switcher.Switch(appRoot); err != nil {
|
||||
return InstallResult{}, installError(stageForSwitchError(err, recordWriteErr), err)
|
||||
}
|
||||
return InstallResult{
|
||||
AppID: record.ID,
|
||||
Version: record.Version,
|
||||
EntrypointPath: filepath.Join(appRoot, "current", request.Entry.App.EntryEXE),
|
||||
Recovery: recovery,
|
||||
}, nil
|
||||
}
|
||||
|
||||
func resolveInstallRequest(request InstallRequest) (installer.PackageExpectation, storage.InstalledApp, error) {
|
||||
if request.DownloadPath == "" {
|
||||
return installer.PackageExpectation{}, storage.InstalledApp{}, fmt.Errorf(
|
||||
"%w: completed download path is empty",
|
||||
ErrInstallRequestInvalid,
|
||||
)
|
||||
}
|
||||
if !request.Entry.Installable || request.Entry.Package == nil {
|
||||
return installer.PackageExpectation{}, storage.InstalledApp{}, fmt.Errorf(
|
||||
"%w: Catalog entry is not installable",
|
||||
ErrInstallRequestInvalid,
|
||||
)
|
||||
}
|
||||
if request.Architecture != catalog.Architecture386 && request.Architecture != catalog.ArchitectureAMD64 {
|
||||
return installer.PackageExpectation{}, storage.InstalledApp{}, fmt.Errorf(
|
||||
"%w: unsupported architecture %q",
|
||||
ErrInstallRequestInvalid,
|
||||
request.Architecture,
|
||||
)
|
||||
}
|
||||
publishedPackage, exists := request.Entry.App.Packages[request.Architecture]
|
||||
if !exists || publishedPackage != *request.Entry.Package {
|
||||
return installer.PackageExpectation{}, storage.InstalledApp{}, fmt.Errorf(
|
||||
"%w: selected package does not match app architecture",
|
||||
ErrInstallRequestInvalid,
|
||||
)
|
||||
}
|
||||
|
||||
app := request.Entry.App
|
||||
return installer.PackageExpectation{
|
||||
Size: publishedPackage.Size,
|
||||
SHA256: publishedPackage.SHA256,
|
||||
App: installer.AppExpectation{
|
||||
ID: app.ID,
|
||||
Version: app.Version,
|
||||
Channel: string(app.Channel),
|
||||
MinOS: string(app.MinOS),
|
||||
Architecture: string(request.Architecture),
|
||||
Entrypoint: app.EntryEXE,
|
||||
RequiresAdmin: app.RequiresAdmin,
|
||||
},
|
||||
}, storage.InstalledApp{
|
||||
SchemaVersion: 1,
|
||||
ID: app.ID,
|
||||
Version: app.Version,
|
||||
Architecture: string(request.Architecture),
|
||||
Channel: string(app.Channel),
|
||||
Files: []storage.InstalledFile{},
|
||||
}, nil
|
||||
}
|
||||
|
||||
func installError(stage InstallStage, err error) error {
|
||||
return &InstallError{Stage: stage, Err: err}
|
||||
}
|
||||
|
||||
func stageForPackageError(err error) InstallStage {
|
||||
var packageErr *installer.PackageError
|
||||
if errors.As(err, &packageErr) {
|
||||
switch packageErr.Stage {
|
||||
case installer.PackageStageManifest:
|
||||
return InstallStageManifest
|
||||
case installer.PackageStageExtract:
|
||||
return InstallStageExtract
|
||||
}
|
||||
}
|
||||
return InstallStageVerify
|
||||
}
|
||||
|
||||
func stageForSwitchError(err error, recordWriteErr error) InstallStage {
|
||||
if errors.Is(err, installer.ErrRollbackFailed) {
|
||||
return InstallStageRollback
|
||||
}
|
||||
if recordWriteErr != nil {
|
||||
return InstallStageRecord
|
||||
}
|
||||
if errors.Is(err, installer.ErrHealthCheckFailed) {
|
||||
return InstallStageHealth
|
||||
}
|
||||
return InstallStageSwitch
|
||||
}
|
||||
@@ -0,0 +1,353 @@
|
||||
package install
|
||||
|
||||
import (
|
||||
"archive/zip"
|
||||
"crypto/sha256"
|
||||
"encoding/hex"
|
||||
"errors"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"testing"
|
||||
|
||||
"softbox.local/core/catalog"
|
||||
"softbox.local/core/installer"
|
||||
"softbox.local/core/storage"
|
||||
)
|
||||
|
||||
func TestInstallServiceInstallsVerifiedPackageAndRecordsPayloadFiles(t *testing.T) {
|
||||
archivePath, publishedPackage := writeInstallPackage(t, "1.2.3", "new executable")
|
||||
appsRoot := filepath.Join(t.TempDir(), "apps")
|
||||
store := storage.NewInstalledAppStore(appsRoot)
|
||||
service := newInstallService(t, store, func(currentPath string) error {
|
||||
_, err := os.Stat(filepath.Join(currentPath, "bin", "App.exe"))
|
||||
return err
|
||||
})
|
||||
|
||||
result, err := service.Install(InstallRequest{
|
||||
Entry: installEntry(publishedPackage, "1.2.3"),
|
||||
Architecture: catalog.ArchitectureAMD64,
|
||||
DownloadPath: archivePath,
|
||||
})
|
||||
if err != nil {
|
||||
t.Fatalf("Install() error = %v", err)
|
||||
}
|
||||
if result.AppID != "test-app" || result.Version != "1.2.3" || result.Recovery.Action != installer.RecoveryNone {
|
||||
t.Fatalf("result = %#v", result)
|
||||
}
|
||||
if got := mustReadFile(t, filepath.Join(appsRoot, "test-app", "current", "bin", "App.exe")); got != "new executable" {
|
||||
t.Fatalf("current entrypoint = %q", got)
|
||||
}
|
||||
record, found, err := store.Read("test-app")
|
||||
if err != nil || !found {
|
||||
t.Fatalf("Read() found=%t err=%v", found, err)
|
||||
}
|
||||
if record.Version != "1.2.3" || len(record.Files) != 2 {
|
||||
t.Fatalf("record = %#v", record)
|
||||
}
|
||||
if record.Files[0].Path != "bin/App.exe" || record.Files[0].Size != int64(len("new executable")) {
|
||||
t.Fatalf("record first file = %#v", record.Files[0])
|
||||
}
|
||||
hash := sha256.Sum256([]byte("new executable"))
|
||||
if record.Files[0].SHA256 != hex.EncodeToString(hash[:]) {
|
||||
t.Fatalf("record first hash = %q", record.Files[0].SHA256)
|
||||
}
|
||||
}
|
||||
|
||||
func TestInstallServiceRejectsCatalogSelectionAndHashBeforeStaging(t *testing.T) {
|
||||
archivePath, publishedPackage := writeInstallPackage(t, "1.2.3", "new executable")
|
||||
tests := []struct {
|
||||
name string
|
||||
entry catalog.Entry
|
||||
wantErr error
|
||||
}{
|
||||
{
|
||||
name: "selected package differs from architecture package",
|
||||
entry: func() catalog.Entry {
|
||||
entry := installEntry(publishedPackage, "1.2.3")
|
||||
forged := publishedPackage
|
||||
forged.SHA256 = "0000000000000000000000000000000000000000000000000000000000000000"
|
||||
entry.Package = &forged
|
||||
return entry
|
||||
}(),
|
||||
wantErr: ErrInstallRequestInvalid,
|
||||
},
|
||||
{
|
||||
name: "download hash differs from Catalog",
|
||||
entry: func() catalog.Entry {
|
||||
entry := installEntry(publishedPackage, "1.2.3")
|
||||
entry.App.Packages[catalog.ArchitectureAMD64] = catalog.Package{
|
||||
Size: publishedPackage.Size,
|
||||
SHA256: "0000000000000000000000000000000000000000000000000000000000000000",
|
||||
Signature: publishedPackage.Signature,
|
||||
URL: publishedPackage.URL,
|
||||
}
|
||||
*entry.Package = entry.App.Packages[catalog.ArchitectureAMD64]
|
||||
return entry
|
||||
}(),
|
||||
wantErr: installer.ErrPackageHashMismatch,
|
||||
},
|
||||
}
|
||||
|
||||
for _, test := range tests {
|
||||
t.Run(test.name, func(t *testing.T) {
|
||||
appsRoot := filepath.Join(t.TempDir(), "apps")
|
||||
store := storage.NewInstalledAppStore(appsRoot)
|
||||
service := newInstallService(t, store, func(string) error { return nil })
|
||||
|
||||
_, err := service.Install(InstallRequest{
|
||||
Entry: test.entry,
|
||||
Architecture: catalog.ArchitectureAMD64,
|
||||
DownloadPath: archivePath,
|
||||
})
|
||||
if !errors.Is(err, test.wantErr) {
|
||||
t.Fatalf("Install() error = %v, want %v", err, test.wantErr)
|
||||
}
|
||||
if stage := installErrorStage(t, err); stage != InstallStageVerify {
|
||||
t.Fatalf("stage = %q, want %q", stage, InstallStageVerify)
|
||||
}
|
||||
if _, statErr := os.Stat(filepath.Join(appsRoot, "test-app", "staging")); !os.IsNotExist(statErr) {
|
||||
t.Fatalf("rejected install left staging, stat error = %v", statErr)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
func TestInstallServiceRollsBackHealthAndRecordWriteFailure(t *testing.T) {
|
||||
appsRoot := filepath.Join(t.TempDir(), "apps")
|
||||
store := storage.NewInstalledAppStore(appsRoot)
|
||||
oldArchive, oldPackage := writeInstallPackage(t, "1.0.0", "old executable")
|
||||
initial := newInstallService(t, store, func(string) error { return nil })
|
||||
if _, err := initial.Install(InstallRequest{
|
||||
Entry: installEntry(oldPackage, "1.0.0"),
|
||||
Architecture: catalog.ArchitectureAMD64,
|
||||
DownloadPath: oldArchive,
|
||||
}); err != nil {
|
||||
t.Fatalf("initial Install() error = %v", err)
|
||||
}
|
||||
|
||||
tests := []struct {
|
||||
name string
|
||||
service func(t *testing.T) *InstallService
|
||||
wantStage InstallStage
|
||||
wantErr error
|
||||
}{
|
||||
{
|
||||
name: "health failure",
|
||||
service: func(t *testing.T) *InstallService {
|
||||
return newInstallService(t, store, func(string) error { return errors.New("health failed") })
|
||||
},
|
||||
wantStage: InstallStageHealth,
|
||||
wantErr: installer.ErrHealthCheckFailed,
|
||||
},
|
||||
{
|
||||
name: "record write failure",
|
||||
service: func(t *testing.T) *InstallService {
|
||||
return newInstallService(t, &failingRecordStore{
|
||||
InstalledAppStore: store,
|
||||
writeErr: errors.New("record disk error"),
|
||||
}, func(string) error { return nil })
|
||||
},
|
||||
wantStage: InstallStageRecord,
|
||||
wantErr: ErrInstallRecordWrite,
|
||||
},
|
||||
}
|
||||
|
||||
for _, test := range tests {
|
||||
t.Run(test.name, func(t *testing.T) {
|
||||
archivePath, publishedPackage := writeInstallPackage(t, "1.1.0", "new executable")
|
||||
_, err := test.service(t).Install(InstallRequest{
|
||||
Entry: installEntry(publishedPackage, "1.1.0"),
|
||||
Architecture: catalog.ArchitectureAMD64,
|
||||
DownloadPath: archivePath,
|
||||
})
|
||||
if !errors.Is(err, test.wantErr) {
|
||||
t.Fatalf("Install() error = %v, want %v", err, test.wantErr)
|
||||
}
|
||||
if stage := installErrorStage(t, err); stage != test.wantStage {
|
||||
t.Fatalf("stage = %q, want %q", stage, test.wantStage)
|
||||
}
|
||||
if got := mustReadFile(t, filepath.Join(appsRoot, "test-app", "current", "bin", "App.exe")); got != "old executable" {
|
||||
t.Fatalf("current entrypoint after failure = %q", got)
|
||||
}
|
||||
record, found, readErr := store.Read("test-app")
|
||||
if readErr != nil || !found || record.Version != "1.0.0" {
|
||||
t.Fatalf("record after failure found=%t record=%#v err=%v", found, record, readErr)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
func TestInstallServiceRecoversPreparedTransactionBeforeExtracting(t *testing.T) {
|
||||
appsRoot := filepath.Join(t.TempDir(), "apps")
|
||||
store := storage.NewInstalledAppStore(appsRoot)
|
||||
appRoot, err := store.EnsureAppRoot("test-app")
|
||||
if err != nil {
|
||||
t.Fatalf("EnsureAppRoot() error = %v", err)
|
||||
}
|
||||
if err := os.MkdirAll(filepath.Join(appRoot, "current"), 0o700); err != nil {
|
||||
t.Fatalf("create current: %v", err)
|
||||
}
|
||||
if err := os.MkdirAll(filepath.Join(appRoot, "staging"), 0o700); err != nil {
|
||||
t.Fatalf("create stale staging: %v", err)
|
||||
}
|
||||
if err := os.WriteFile(
|
||||
filepath.Join(appRoot, "install-transaction.json"),
|
||||
[]byte(`{"schema_version":1,"phase":"prepared","had_current":true}`),
|
||||
0o600,
|
||||
); err != nil {
|
||||
t.Fatalf("write transaction: %v", err)
|
||||
}
|
||||
|
||||
archivePath, publishedPackage := writeInstallPackage(t, "1.2.3", "new executable")
|
||||
service := newInstallService(t, store, func(string) error { return nil })
|
||||
result, err := service.Install(InstallRequest{
|
||||
Entry: installEntry(publishedPackage, "1.2.3"),
|
||||
Architecture: catalog.ArchitectureAMD64,
|
||||
DownloadPath: archivePath,
|
||||
})
|
||||
if err != nil {
|
||||
t.Fatalf("Install() error = %v", err)
|
||||
}
|
||||
if result.Recovery.Action != installer.RecoveryAborted {
|
||||
t.Fatalf("recovery action = %q, want %q", result.Recovery.Action, installer.RecoveryAborted)
|
||||
}
|
||||
if got := mustReadFile(t, filepath.Join(appRoot, "current", "bin", "App.exe")); got != "new executable" {
|
||||
t.Fatalf("current entrypoint = %q", got)
|
||||
}
|
||||
if _, statErr := os.Stat(filepath.Join(appRoot, "staging")); !os.IsNotExist(statErr) {
|
||||
t.Fatalf("staging remains, stat error = %v", statErr)
|
||||
}
|
||||
if _, statErr := os.Stat(filepath.Join(appRoot, "install-transaction.json")); !os.IsNotExist(statErr) {
|
||||
t.Fatalf("transaction remains, stat error = %v", statErr)
|
||||
}
|
||||
}
|
||||
|
||||
type failingRecordStore struct {
|
||||
*storage.InstalledAppStore
|
||||
writeErr error
|
||||
}
|
||||
|
||||
func (store *failingRecordStore) Write(storage.InstalledApp) error {
|
||||
return store.writeErr
|
||||
}
|
||||
|
||||
func newInstallService(
|
||||
t *testing.T,
|
||||
store InstallRecordStore,
|
||||
health installer.HealthCheck,
|
||||
) *InstallService {
|
||||
t.Helper()
|
||||
extractor, err := installer.NewExtractor(installTestLimits())
|
||||
if err != nil {
|
||||
t.Fatalf("NewExtractor() error = %v", err)
|
||||
}
|
||||
service, err := NewInstallService(extractor, store, health)
|
||||
if err != nil {
|
||||
t.Fatalf("NewInstallService() error = %v", err)
|
||||
}
|
||||
return service
|
||||
}
|
||||
|
||||
func installTestLimits() installer.Limits {
|
||||
return installer.Limits{
|
||||
MaxEntries: 20,
|
||||
MaxArchiveBytes: 64 * 1024,
|
||||
MaxCentralDirectoryBytes: 4 * 1024,
|
||||
MaxUncompressedBytes: 64 * 1024,
|
||||
MaxCompressionRatio: 100,
|
||||
}
|
||||
}
|
||||
|
||||
func installEntry(publishedPackage catalog.Package, version string) catalog.Entry {
|
||||
selectedPackage := publishedPackage
|
||||
return catalog.Entry{
|
||||
App: catalog.App{
|
||||
ID: "test-app",
|
||||
Version: version,
|
||||
Channel: catalog.ReleaseStable,
|
||||
Status: catalog.CatalogStatusActive,
|
||||
MinOS: catalog.Windows10,
|
||||
Architectures: []catalog.Architecture{catalog.ArchitectureAMD64},
|
||||
EntryEXE: "bin/App.exe",
|
||||
Packages: map[catalog.Architecture]catalog.Package{
|
||||
catalog.ArchitectureAMD64: publishedPackage,
|
||||
},
|
||||
},
|
||||
Package: &selectedPackage,
|
||||
Installable: true,
|
||||
}
|
||||
}
|
||||
|
||||
func writeInstallPackage(t *testing.T, version, executable string) (string, catalog.Package) {
|
||||
t.Helper()
|
||||
path := filepath.Join(t.TempDir(), "package.download")
|
||||
file, err := os.Create(path)
|
||||
if err != nil {
|
||||
t.Fatalf("create package: %v", err)
|
||||
}
|
||||
writer := zip.NewWriter(file)
|
||||
entries := []struct {
|
||||
name string
|
||||
body []byte
|
||||
mode os.FileMode
|
||||
}{
|
||||
{name: "app.json", body: installManifest(version)},
|
||||
{name: "payload/bin/App.exe", body: []byte(executable), mode: 0o755},
|
||||
{name: "payload/readme.txt", body: []byte("readme")},
|
||||
}
|
||||
for _, entry := range entries {
|
||||
header := &zip.FileHeader{Name: entry.name}
|
||||
mode := entry.mode
|
||||
if mode == 0 {
|
||||
mode = 0o600
|
||||
}
|
||||
header.SetMode(mode)
|
||||
part, err := writer.CreateHeader(header)
|
||||
if err != nil {
|
||||
t.Fatalf("create ZIP entry: %v", err)
|
||||
}
|
||||
if _, err := part.Write(entry.body); err != nil {
|
||||
t.Fatalf("write ZIP entry: %v", err)
|
||||
}
|
||||
}
|
||||
if err := writer.Close(); err != nil {
|
||||
file.Close()
|
||||
t.Fatalf("close ZIP writer: %v", err)
|
||||
}
|
||||
if err := file.Close(); err != nil {
|
||||
t.Fatalf("close package: %v", err)
|
||||
}
|
||||
document, err := os.ReadFile(path)
|
||||
if err != nil {
|
||||
t.Fatalf("read package: %v", err)
|
||||
}
|
||||
hash := sha256.Sum256(document)
|
||||
return path, catalog.Package{
|
||||
URL: "https://download.invalid/test-app.zip",
|
||||
Size: int64(len(document)),
|
||||
SHA256: hex.EncodeToString(hash[:]),
|
||||
Signature: "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==",
|
||||
}
|
||||
}
|
||||
|
||||
func installManifest(version string) []byte {
|
||||
return []byte(`{"schema_version":1,"id":"test-app","name":"Test App","vendor":"SoftBox","version":"` + version + `","channel":"stable","min_os":"windows-10","architecture":"amd64","entrypoint":"bin/App.exe","working_directory":".","product_id":"test-product","supports_trial":false,"requires_admin":false,"data_policy":"local-app-data","update_policy":"managed-by-softbox"}`)
|
||||
}
|
||||
|
||||
func installErrorStage(t *testing.T, err error) InstallStage {
|
||||
t.Helper()
|
||||
var installErr *InstallError
|
||||
if !errors.As(err, &installErr) {
|
||||
t.Fatalf("error %v is not InstallError", err)
|
||||
}
|
||||
return installErr.Stage
|
||||
}
|
||||
|
||||
func mustReadFile(t *testing.T, path string) string {
|
||||
t.Helper()
|
||||
document, err := os.ReadFile(path)
|
||||
if err != nil {
|
||||
t.Fatalf("read %s: %v", path, err)
|
||||
}
|
||||
return string(document)
|
||||
}
|
||||
@@ -2,6 +2,8 @@ package installer
|
||||
|
||||
import (
|
||||
"archive/zip"
|
||||
"crypto/sha256"
|
||||
"encoding/hex"
|
||||
"errors"
|
||||
"fmt"
|
||||
"io"
|
||||
@@ -43,6 +45,15 @@ type ExtractResult struct {
|
||||
Files int
|
||||
Bytes int64
|
||||
EntrypointPath string
|
||||
PayloadFiles []ExtractedFile
|
||||
}
|
||||
|
||||
// ExtractedFile is one payload file written to staging after ZIP CRC and
|
||||
// length validation. Its digest is calculated from the bytes written there.
|
||||
type ExtractedFile struct {
|
||||
Path string
|
||||
Size int64
|
||||
SHA256 string
|
||||
}
|
||||
|
||||
type plannedEntry struct {
|
||||
@@ -89,7 +100,6 @@ func (extractor Extractor) extract(
|
||||
if err := extractor.limits.validate(); err != nil {
|
||||
return ExtractResult{}, err
|
||||
}
|
||||
fence := effectiveDurability(extractor.durability)
|
||||
normalizedEntrypoint, err := normalizeEntrypoint(entrypoint)
|
||||
if err != nil {
|
||||
return ExtractResult{}, err
|
||||
@@ -98,9 +108,18 @@ func (extractor Extractor) extract(
|
||||
if err != nil {
|
||||
return ExtractResult{}, err
|
||||
}
|
||||
return extractor.extractPlan(destination, normalizedEntrypoint, plan)
|
||||
}
|
||||
|
||||
func (extractor Extractor) extractPlan(
|
||||
destination string,
|
||||
entrypoint string,
|
||||
plan []plannedEntry,
|
||||
) (result ExtractResult, err error) {
|
||||
fence := effectiveDurability(extractor.durability)
|
||||
destinationRoot, entrypointPath, err := planOutputPaths(
|
||||
destination,
|
||||
normalizedEntrypoint,
|
||||
entrypoint,
|
||||
plan,
|
||||
)
|
||||
if err != nil {
|
||||
@@ -161,7 +180,11 @@ func (extractor Extractor) extract(
|
||||
if readLimit < math.MaxInt64 {
|
||||
readLimit++
|
||||
}
|
||||
copied, copyErr := io.Copy(output, io.LimitReader(source, readLimit))
|
||||
digest := sha256.New()
|
||||
copied, copyErr := io.Copy(
|
||||
io.MultiWriter(output, digest),
|
||||
io.LimitReader(source, readLimit),
|
||||
)
|
||||
closeSourceErr := source.Close()
|
||||
if copyErr != nil {
|
||||
_ = output.Close()
|
||||
@@ -194,6 +217,11 @@ func (extractor Extractor) extract(
|
||||
}
|
||||
written += copied
|
||||
result.Files++
|
||||
result.PayloadFiles = append(result.PayloadFiles, ExtractedFile{
|
||||
Path: entry.outputPath,
|
||||
Size: copied,
|
||||
SHA256: hex.EncodeToString(digest.Sum(nil)),
|
||||
})
|
||||
}
|
||||
if err := syncStagingTree(fence, destinationRoot); err != nil {
|
||||
return ExtractResult{}, err
|
||||
|
||||
@@ -36,8 +36,8 @@ func (err *RollbackError) Error() string {
|
||||
return fmt.Sprintf("%s: health=%v; rollback=%v", ErrRollbackFailed, err.Health, err.Rollback)
|
||||
}
|
||||
|
||||
func (err *RollbackError) Unwrap() error {
|
||||
return ErrRollbackFailed
|
||||
func (err *RollbackError) Unwrap() []error {
|
||||
return []error{ErrRollbackFailed, err.Health, err.Rollback}
|
||||
}
|
||||
|
||||
// Switcher activates a verified staging directory and runs an injected check.
|
||||
@@ -141,7 +141,7 @@ func (switcher *Switcher) Switch(root string) error {
|
||||
if err := removeTransactionWithFence(layout, fence); err != nil {
|
||||
return &RollbackError{Health: healthErr, Rollback: err}
|
||||
}
|
||||
return fmt.Errorf("%w: %v", ErrHealthCheckFailed, healthErr)
|
||||
return fmt.Errorf("%w: %w", ErrHealthCheckFailed, healthErr)
|
||||
}
|
||||
|
||||
record.Phase = phaseCommitted
|
||||
|
||||
@@ -0,0 +1,391 @@
|
||||
package installer
|
||||
|
||||
import (
|
||||
"archive/zip"
|
||||
"bytes"
|
||||
"crypto/sha256"
|
||||
"crypto/subtle"
|
||||
"encoding/hex"
|
||||
"encoding/json"
|
||||
"errors"
|
||||
"fmt"
|
||||
"io"
|
||||
"os"
|
||||
"regexp"
|
||||
|
||||
"softbox.local/core/domain"
|
||||
"softbox.local/core/internal/safepath"
|
||||
)
|
||||
|
||||
const MaxAppManifestBytes = 1 << 20
|
||||
|
||||
var (
|
||||
ErrPackageExpectationInvalid = errors.New("invalid verified package expectation")
|
||||
ErrPackageHashMismatch = errors.New("package SHA-256 does not match Catalog")
|
||||
ErrAppManifestTooLarge = errors.New("package app.json exceeds size limit")
|
||||
ErrAppManifestInvalid = errors.New("package app.json is invalid")
|
||||
ErrPackageIdentityMismatch = errors.New("package app.json does not match Catalog")
|
||||
)
|
||||
|
||||
var packageIDPattern = regexp.MustCompile(`^[a-z0-9-]+$`)
|
||||
|
||||
// PackageStage identifies the point at which a verified package install
|
||||
// stopped. It is intentionally independent of UI wording.
|
||||
type PackageStage string
|
||||
|
||||
const (
|
||||
PackageStageVerify PackageStage = "verify"
|
||||
PackageStageManifest PackageStage = "manifest"
|
||||
PackageStageExtract PackageStage = "extract"
|
||||
)
|
||||
|
||||
// PackageError preserves the underlying safe failure while making the package
|
||||
// boundary observable to its application caller.
|
||||
type PackageError struct {
|
||||
Stage PackageStage
|
||||
Err error
|
||||
}
|
||||
|
||||
func (err *PackageError) Error() string {
|
||||
return fmt.Sprintf("package %s: %v", err.Stage, err.Err)
|
||||
}
|
||||
|
||||
func (err *PackageError) Unwrap() error {
|
||||
return err.Err
|
||||
}
|
||||
|
||||
// AppExpectation is the portion of app.json that must equal the selected
|
||||
// signed Catalog entry. The remaining v1 fields are still validated locally.
|
||||
type AppExpectation struct {
|
||||
ID string
|
||||
Version string
|
||||
Channel string
|
||||
MinOS string
|
||||
Architecture string
|
||||
Entrypoint string
|
||||
RequiresAdmin bool
|
||||
}
|
||||
|
||||
// PackageExpectation is selected from a verified Catalog package. The outer
|
||||
// Catalog signature is the trust root for Size and SHA256.
|
||||
type PackageExpectation struct {
|
||||
Size int64
|
||||
SHA256 string
|
||||
App AppExpectation
|
||||
}
|
||||
|
||||
type packageAppManifest struct {
|
||||
SchemaVersion int `json:"schema_version"`
|
||||
ID string `json:"id"`
|
||||
Name string `json:"name"`
|
||||
Vendor string `json:"vendor"`
|
||||
Version string `json:"version"`
|
||||
Channel string `json:"channel"`
|
||||
MinOS string `json:"min_os"`
|
||||
Architecture string `json:"architecture"`
|
||||
Entrypoint string `json:"entrypoint"`
|
||||
WorkingDir string `json:"working_directory"`
|
||||
ProductID string `json:"product_id"`
|
||||
SupportsTrial bool `json:"supports_trial"`
|
||||
RequiresAdmin bool `json:"requires_admin"`
|
||||
DataPolicy string `json:"data_policy"`
|
||||
UpdatePolicy string `json:"update_policy"`
|
||||
}
|
||||
|
||||
var appManifestFields = map[string]struct{}{
|
||||
"schema_version": {},
|
||||
"id": {},
|
||||
"name": {},
|
||||
"vendor": {},
|
||||
"version": {},
|
||||
"channel": {},
|
||||
"min_os": {},
|
||||
"architecture": {},
|
||||
"entrypoint": {},
|
||||
"working_directory": {},
|
||||
"product_id": {},
|
||||
"supports_trial": {},
|
||||
"requires_admin": {},
|
||||
"data_policy": {},
|
||||
"update_policy": {},
|
||||
}
|
||||
|
||||
// ExtractVerifiedFile preserves one file handle from Catalog size/SHA-256
|
||||
// verification through ZIP scanning, manifest comparison and safe extraction.
|
||||
func (extractor Extractor) ExtractVerifiedFile(
|
||||
zipPath string,
|
||||
destination string,
|
||||
expectation PackageExpectation,
|
||||
) (ExtractResult, error) {
|
||||
expectedHash, err := expectation.validate()
|
||||
if err != nil {
|
||||
return ExtractResult{}, packageError(PackageStageVerify, err)
|
||||
}
|
||||
|
||||
file, size, err := extractor.openArchiveFile(zipPath, expectation.Size)
|
||||
if err != nil {
|
||||
return ExtractResult{}, packageError(PackageStageVerify, err)
|
||||
}
|
||||
defer file.Close()
|
||||
|
||||
if err := verifyPackageSHA256(file, size, expectedHash); err != nil {
|
||||
return ExtractResult{}, packageError(PackageStageVerify, err)
|
||||
}
|
||||
if err := extractor.scanOpenedArchive(file, size); err != nil {
|
||||
return ExtractResult{}, packageError(PackageStageVerify, err)
|
||||
}
|
||||
archive, err := zip.NewReader(file, size)
|
||||
if err != nil {
|
||||
return ExtractResult{}, packageError(
|
||||
PackageStageVerify,
|
||||
fmt.Errorf("%w: %v", ErrInvalidArchive, err),
|
||||
)
|
||||
}
|
||||
|
||||
normalizedEntrypoint, err := normalizeEntrypoint(expectation.App.Entrypoint)
|
||||
if err != nil {
|
||||
return ExtractResult{}, packageError(PackageStageManifest, err)
|
||||
}
|
||||
plan, err := extractor.preflight(archive, normalizedEntrypoint)
|
||||
if err != nil {
|
||||
return ExtractResult{}, packageError(PackageStageVerify, err)
|
||||
}
|
||||
manifest, err := readPackageAppManifest(archive)
|
||||
if err != nil {
|
||||
return ExtractResult{}, packageError(PackageStageManifest, err)
|
||||
}
|
||||
if err := manifest.matches(expectation.App); err != nil {
|
||||
return ExtractResult{}, packageError(PackageStageManifest, err)
|
||||
}
|
||||
result, err := extractor.extractPlan(destination, normalizedEntrypoint, plan)
|
||||
if err != nil {
|
||||
return ExtractResult{}, packageError(PackageStageExtract, err)
|
||||
}
|
||||
return result, nil
|
||||
}
|
||||
|
||||
func packageError(stage PackageStage, err error) error {
|
||||
return &PackageError{Stage: stage, Err: err}
|
||||
}
|
||||
|
||||
func (expectation PackageExpectation) validate() ([]byte, error) {
|
||||
if expectation.Size <= 0 {
|
||||
return nil, fmt.Errorf("%w: package size must be positive", ErrPackageExpectationInvalid)
|
||||
}
|
||||
expectedHash, err := hex.DecodeString(expectation.SHA256)
|
||||
if err != nil || len(expectedHash) != sha256.Size {
|
||||
return nil, fmt.Errorf("%w: SHA-256 must be 32 bytes", ErrPackageExpectationInvalid)
|
||||
}
|
||||
if err := validateExpectationApp(expectation.App); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return expectedHash, nil
|
||||
}
|
||||
|
||||
func validateExpectationApp(expectation AppExpectation) error {
|
||||
if !packageIDPattern.MatchString(expectation.ID) {
|
||||
return fmt.Errorf("%w: invalid app id", ErrPackageExpectationInvalid)
|
||||
}
|
||||
if _, err := domain.ParseSemVer(expectation.Version); err != nil {
|
||||
return fmt.Errorf("%w: version: %v", ErrPackageExpectationInvalid, err)
|
||||
}
|
||||
if expectation.Channel != "stable" {
|
||||
return fmt.Errorf("%w: channel=%q", ErrPackageExpectationInvalid, expectation.Channel)
|
||||
}
|
||||
if !isSupportedMinOS(expectation.MinOS) {
|
||||
return fmt.Errorf("%w: min_os=%q", ErrPackageExpectationInvalid, expectation.MinOS)
|
||||
}
|
||||
if expectation.Architecture != "386" && expectation.Architecture != "amd64" {
|
||||
return fmt.Errorf("%w: architecture=%q", ErrPackageExpectationInvalid, expectation.Architecture)
|
||||
}
|
||||
if _, err := normalizeEntrypoint(expectation.Entrypoint); err != nil {
|
||||
return fmt.Errorf("%w: %v", ErrPackageExpectationInvalid, err)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
func verifyPackageSHA256(file *os.File, size int64, expectedHash []byte) error {
|
||||
if file == nil || size <= 0 {
|
||||
return fmt.Errorf("%w: package handle or size is invalid", ErrInvalidArchive)
|
||||
}
|
||||
hasher := sha256.New()
|
||||
copied, err := io.Copy(hasher, io.NewSectionReader(file, 0, size))
|
||||
if err != nil {
|
||||
return fmt.Errorf("%w: read package: %v", ErrInvalidArchive, err)
|
||||
}
|
||||
if copied != size {
|
||||
return fmt.Errorf("%w: got %d bytes while hashing, expected %d", ErrArchiveSizeMismatch, copied, size)
|
||||
}
|
||||
info, err := file.Stat()
|
||||
if err != nil {
|
||||
return fmt.Errorf("%w: stat package after hashing: %v", ErrInvalidArchive, err)
|
||||
}
|
||||
if !info.Mode().IsRegular() || info.Size() != size {
|
||||
return fmt.Errorf("%w: package changed while hashing", ErrArchiveSizeMismatch)
|
||||
}
|
||||
if subtle.ConstantTimeCompare(hasher.Sum(nil), expectedHash) != 1 {
|
||||
return ErrPackageHashMismatch
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
func readPackageAppManifest(archive *zip.Reader) (packageAppManifest, error) {
|
||||
var appFile *zip.File
|
||||
for _, file := range archive.File {
|
||||
if file.Name != "app.json" {
|
||||
continue
|
||||
}
|
||||
if appFile != nil {
|
||||
return packageAppManifest{}, fmt.Errorf("%w: duplicate app.json", ErrAppManifestInvalid)
|
||||
}
|
||||
appFile = file
|
||||
}
|
||||
if appFile == nil {
|
||||
return packageAppManifest{}, ErrAppManifestMissing
|
||||
}
|
||||
|
||||
reader, err := appFile.Open()
|
||||
if err != nil {
|
||||
return packageAppManifest{}, fmt.Errorf("%w: open: %v", ErrAppManifestInvalid, err)
|
||||
}
|
||||
document, readErr := io.ReadAll(io.LimitReader(reader, MaxAppManifestBytes+1))
|
||||
closeErr := reader.Close()
|
||||
if readErr != nil {
|
||||
return packageAppManifest{}, fmt.Errorf("%w: read: %v", ErrAppManifestInvalid, readErr)
|
||||
}
|
||||
if closeErr != nil {
|
||||
return packageAppManifest{}, fmt.Errorf("%w: close: %v", ErrAppManifestInvalid, closeErr)
|
||||
}
|
||||
if len(document) > MaxAppManifestBytes {
|
||||
return packageAppManifest{}, ErrAppManifestTooLarge
|
||||
}
|
||||
return parsePackageAppManifest(document)
|
||||
}
|
||||
|
||||
func parsePackageAppManifest(document []byte) (packageAppManifest, error) {
|
||||
if err := validateManifestObject(document); err != nil {
|
||||
return packageAppManifest{}, err
|
||||
}
|
||||
var manifest packageAppManifest
|
||||
decoder := json.NewDecoder(bytes.NewReader(document))
|
||||
decoder.DisallowUnknownFields()
|
||||
if err := decoder.Decode(&manifest); err != nil {
|
||||
return packageAppManifest{}, fmt.Errorf("%w: decode: %v", ErrAppManifestInvalid, err)
|
||||
}
|
||||
if err := ensureManifestEOF(decoder); err != nil {
|
||||
return packageAppManifest{}, err
|
||||
}
|
||||
if err := manifest.validate(); err != nil {
|
||||
return packageAppManifest{}, err
|
||||
}
|
||||
return manifest, nil
|
||||
}
|
||||
|
||||
func validateManifestObject(document []byte) error {
|
||||
decoder := json.NewDecoder(bytes.NewReader(document))
|
||||
token, err := decoder.Token()
|
||||
if err != nil {
|
||||
return fmt.Errorf("%w: read object: %v", ErrAppManifestInvalid, err)
|
||||
}
|
||||
delimiter, ok := token.(json.Delim)
|
||||
if !ok || delimiter != '{' {
|
||||
return fmt.Errorf("%w: root must be an object", ErrAppManifestInvalid)
|
||||
}
|
||||
seen := make(map[string]struct{}, len(appManifestFields))
|
||||
for decoder.More() {
|
||||
token, err := decoder.Token()
|
||||
if err != nil {
|
||||
return fmt.Errorf("%w: read field: %v", ErrAppManifestInvalid, err)
|
||||
}
|
||||
name, ok := token.(string)
|
||||
if !ok {
|
||||
return fmt.Errorf("%w: field name is not a string", ErrAppManifestInvalid)
|
||||
}
|
||||
if _, exists := appManifestFields[name]; !exists {
|
||||
return fmt.Errorf("%w: unknown field %q", ErrAppManifestInvalid, name)
|
||||
}
|
||||
if _, exists := seen[name]; exists {
|
||||
return fmt.Errorf("%w: duplicate field %q", ErrAppManifestInvalid, name)
|
||||
}
|
||||
seen[name] = struct{}{}
|
||||
var discard json.RawMessage
|
||||
if err := decoder.Decode(&discard); err != nil {
|
||||
return fmt.Errorf("%w: read field %q: %v", ErrAppManifestInvalid, name, err)
|
||||
}
|
||||
}
|
||||
if _, err := decoder.Token(); err != nil {
|
||||
return fmt.Errorf("%w: close object: %v", ErrAppManifestInvalid, err)
|
||||
}
|
||||
if len(seen) != len(appManifestFields) {
|
||||
for field := range appManifestFields {
|
||||
if _, exists := seen[field]; !exists {
|
||||
return fmt.Errorf("%w: missing field %q", ErrAppManifestInvalid, field)
|
||||
}
|
||||
}
|
||||
}
|
||||
return ensureManifestEOF(decoder)
|
||||
}
|
||||
|
||||
func ensureManifestEOF(decoder *json.Decoder) error {
|
||||
var extra any
|
||||
if err := decoder.Decode(&extra); err != io.EOF {
|
||||
if err == nil {
|
||||
return fmt.Errorf("%w: trailing JSON value", ErrAppManifestInvalid)
|
||||
}
|
||||
return fmt.Errorf("%w: trailing data: %v", ErrAppManifestInvalid, err)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
func (manifest packageAppManifest) validate() error {
|
||||
if manifest.SchemaVersion != 1 {
|
||||
return fmt.Errorf("%w: schema_version=%d", ErrAppManifestInvalid, manifest.SchemaVersion)
|
||||
}
|
||||
if !packageIDPattern.MatchString(manifest.ID) {
|
||||
return fmt.Errorf("%w: invalid id", ErrAppManifestInvalid)
|
||||
}
|
||||
if manifest.Name == "" || manifest.Vendor == "" {
|
||||
return fmt.Errorf("%w: name and vendor must not be empty", ErrAppManifestInvalid)
|
||||
}
|
||||
if _, err := domain.ParseSemVer(manifest.Version); err != nil {
|
||||
return fmt.Errorf("%w: version: %v", ErrAppManifestInvalid, err)
|
||||
}
|
||||
if manifest.Channel != "stable" || !isSupportedMinOS(manifest.MinOS) {
|
||||
return fmt.Errorf("%w: channel or min_os", ErrAppManifestInvalid)
|
||||
}
|
||||
if manifest.Architecture != "386" && manifest.Architecture != "amd64" {
|
||||
return fmt.Errorf("%w: architecture=%q", ErrAppManifestInvalid, manifest.Architecture)
|
||||
}
|
||||
if _, err := normalizeEntrypoint(manifest.Entrypoint); err != nil {
|
||||
return fmt.Errorf("%w: %v", ErrAppManifestInvalid, err)
|
||||
}
|
||||
if manifest.WorkingDir != "." {
|
||||
if err := safepath.ValidateRelative(manifest.WorkingDir); err != nil {
|
||||
return fmt.Errorf("%w: working_directory: %v", ErrAppManifestInvalid, err)
|
||||
}
|
||||
}
|
||||
if !packageIDPattern.MatchString(manifest.ProductID) {
|
||||
return fmt.Errorf("%w: invalid product_id", ErrAppManifestInvalid)
|
||||
}
|
||||
if manifest.DataPolicy != "local-app-data" || manifest.UpdatePolicy != "managed-by-softbox" {
|
||||
return fmt.Errorf("%w: data_policy or update_policy", ErrAppManifestInvalid)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
func (manifest packageAppManifest) matches(expectation AppExpectation) error {
|
||||
if manifest.ID != expectation.ID ||
|
||||
manifest.Version != expectation.Version ||
|
||||
manifest.Channel != expectation.Channel ||
|
||||
manifest.MinOS != expectation.MinOS ||
|
||||
manifest.Architecture != expectation.Architecture ||
|
||||
manifest.Entrypoint != expectation.Entrypoint ||
|
||||
manifest.RequiresAdmin != expectation.RequiresAdmin {
|
||||
return ErrPackageIdentityMismatch
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
func isSupportedMinOS(value string) bool {
|
||||
return value == "windows-7-sp1" || value == "windows-10" || value == "windows-11"
|
||||
}
|
||||
@@ -0,0 +1,203 @@
|
||||
package installer
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"crypto/sha256"
|
||||
"encoding/hex"
|
||||
"errors"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"testing"
|
||||
)
|
||||
|
||||
func TestExtractorExtractVerifiedFile(t *testing.T) {
|
||||
archivePath := writeTestZIP(t, []testZIPEntry{
|
||||
{name: "app.json", body: validAppManifest("1.2.3", "bin/App.exe")},
|
||||
{name: "payload/bin/App.exe", body: []byte("executable"), mode: 0o755},
|
||||
{name: "payload/readme.txt", body: []byte("hello")},
|
||||
})
|
||||
destination := filepath.Join(t.TempDir(), "staging")
|
||||
extractor := mustExtractor(t, testLimits())
|
||||
|
||||
result, err := extractor.ExtractVerifiedFile(
|
||||
archivePath,
|
||||
destination,
|
||||
verifiedExpectation(t, archivePath, "1.2.3", "bin/App.exe"),
|
||||
)
|
||||
if err != nil {
|
||||
t.Fatalf("ExtractVerifiedFile() error = %v", err)
|
||||
}
|
||||
if result.Files != 2 || len(result.PayloadFiles) != 2 {
|
||||
t.Fatalf("files = %d, payload files = %d, want 2", result.Files, len(result.PayloadFiles))
|
||||
}
|
||||
if result.PayloadFiles[0].Path != "bin/App.exe" || result.PayloadFiles[0].Size != int64(len("executable")) {
|
||||
t.Fatalf("first payload file = %#v", result.PayloadFiles[0])
|
||||
}
|
||||
wantHash := sha256.Sum256([]byte("executable"))
|
||||
if result.PayloadFiles[0].SHA256 != hex.EncodeToString(wantHash[:]) {
|
||||
t.Fatalf("first payload hash = %q", result.PayloadFiles[0].SHA256)
|
||||
}
|
||||
if _, err := os.Stat(result.EntrypointPath); err != nil {
|
||||
t.Fatalf("entrypoint stat error = %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestExtractorExtractVerifiedFileRejectsBeforeStaging(t *testing.T) {
|
||||
archivePath := writeTestZIP(t, []testZIPEntry{
|
||||
{name: "app.json", body: validAppManifest("1.2.3", "App.exe")},
|
||||
{name: "payload/App.exe", body: []byte("executable"), mode: 0o755},
|
||||
})
|
||||
|
||||
tests := []struct {
|
||||
name string
|
||||
modify func(PackageExpectation) PackageExpectation
|
||||
wantErr error
|
||||
stage PackageStage
|
||||
}{
|
||||
{
|
||||
name: "hash mismatch",
|
||||
modify: func(expectation PackageExpectation) PackageExpectation {
|
||||
expectation.SHA256 = "0000000000000000000000000000000000000000000000000000000000000000"
|
||||
return expectation
|
||||
},
|
||||
wantErr: ErrPackageHashMismatch,
|
||||
stage: PackageStageVerify,
|
||||
},
|
||||
{
|
||||
name: "app manifest identity mismatch",
|
||||
modify: func(expectation PackageExpectation) PackageExpectation {
|
||||
expectation.App.Version = "9.9.9"
|
||||
return expectation
|
||||
},
|
||||
wantErr: ErrPackageIdentityMismatch,
|
||||
stage: PackageStageManifest,
|
||||
},
|
||||
}
|
||||
|
||||
for _, test := range tests {
|
||||
t.Run(test.name, func(t *testing.T) {
|
||||
destination := filepath.Join(t.TempDir(), "staging")
|
||||
extractor := mustExtractor(t, testLimits())
|
||||
expectation := test.modify(verifiedExpectation(t, archivePath, "1.2.3", "App.exe"))
|
||||
|
||||
_, err := extractor.ExtractVerifiedFile(archivePath, destination, expectation)
|
||||
if !errors.Is(err, test.wantErr) {
|
||||
t.Fatalf("ExtractVerifiedFile() error = %v, want %v", err, test.wantErr)
|
||||
}
|
||||
var packageErr *PackageError
|
||||
if !errors.As(err, &packageErr) || packageErr.Stage != test.stage {
|
||||
t.Fatalf("package error = %#v, want stage %q", packageErr, test.stage)
|
||||
}
|
||||
if _, statErr := os.Stat(destination); !os.IsNotExist(statErr) {
|
||||
t.Fatalf("rejected package left staging, stat error = %v", statErr)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
func TestExtractorExtractVerifiedFileRejectsStrictAppManifest(t *testing.T) {
|
||||
manifest := validAppManifest("1.2.3", "App.exe")
|
||||
archivePath := writeTestZIP(t, []testZIPEntry{
|
||||
{name: "app.json", body: append(manifest[:len(manifest)-1], []byte(`,"unexpected":true}`)...)},
|
||||
{name: "payload/App.exe", body: []byte("executable"), mode: 0o755},
|
||||
})
|
||||
destination := filepath.Join(t.TempDir(), "staging")
|
||||
extractor := mustExtractor(t, testLimits())
|
||||
|
||||
_, err := extractor.ExtractVerifiedFile(
|
||||
archivePath,
|
||||
destination,
|
||||
verifiedExpectation(t, archivePath, "1.2.3", "App.exe"),
|
||||
)
|
||||
if !errors.Is(err, ErrAppManifestInvalid) {
|
||||
t.Fatalf("ExtractVerifiedFile() error = %v, want %v", err, ErrAppManifestInvalid)
|
||||
}
|
||||
if _, statErr := os.Stat(destination); !os.IsNotExist(statErr) {
|
||||
t.Fatalf("invalid manifest left staging, stat error = %v", statErr)
|
||||
}
|
||||
}
|
||||
|
||||
func TestExtractorExtractVerifiedFileRejectsNonRegularDownload(t *testing.T) {
|
||||
destination := filepath.Join(t.TempDir(), "staging")
|
||||
extractor := mustExtractor(t, testLimits())
|
||||
_, err := extractor.ExtractVerifiedFile(
|
||||
t.TempDir(),
|
||||
destination,
|
||||
PackageExpectation{
|
||||
Size: 1,
|
||||
SHA256: "0000000000000000000000000000000000000000000000000000000000000000",
|
||||
App: AppExpectation{
|
||||
ID: "test-app",
|
||||
Version: "1.2.3",
|
||||
Channel: "stable",
|
||||
MinOS: "windows-10",
|
||||
Architecture: "amd64",
|
||||
Entrypoint: "App.exe",
|
||||
},
|
||||
},
|
||||
)
|
||||
if !errors.Is(err, ErrInvalidArchive) {
|
||||
t.Fatalf("ExtractVerifiedFile() error = %v, want %v", err, ErrInvalidArchive)
|
||||
}
|
||||
if _, statErr := os.Stat(destination); !os.IsNotExist(statErr) {
|
||||
t.Fatalf("non-regular download left staging, stat error = %v", statErr)
|
||||
}
|
||||
}
|
||||
|
||||
func TestExtractorExtractVerifiedFileBoundsAppManifest(t *testing.T) {
|
||||
manifest := append(validAppManifest("1.2.3", "App.exe"), bytes.Repeat([]byte(" "), MaxAppManifestBytes)...)
|
||||
archivePath := writeTestZIP(t, []testZIPEntry{
|
||||
{name: "app.json", body: manifest},
|
||||
{name: "payload/App.exe", body: []byte("executable"), mode: 0o755},
|
||||
})
|
||||
destination := filepath.Join(t.TempDir(), "staging")
|
||||
extractor := mustExtractor(t, Limits{
|
||||
MaxEntries: 20,
|
||||
MaxArchiveBytes: 2 * MaxAppManifestBytes,
|
||||
MaxCentralDirectoryBytes: 4 * 1024,
|
||||
MaxUncompressedBytes: 2 * MaxAppManifestBytes,
|
||||
MaxCompressionRatio: 100,
|
||||
})
|
||||
|
||||
_, err := extractor.ExtractVerifiedFile(
|
||||
archivePath,
|
||||
destination,
|
||||
verifiedExpectation(t, archivePath, "1.2.3", "App.exe"),
|
||||
)
|
||||
if !errors.Is(err, ErrAppManifestTooLarge) {
|
||||
t.Fatalf("ExtractVerifiedFile() error = %v, want %v", err, ErrAppManifestTooLarge)
|
||||
}
|
||||
var packageErr *PackageError
|
||||
if !errors.As(err, &packageErr) || packageErr.Stage != PackageStageManifest {
|
||||
t.Fatalf("package error = %#v, want manifest stage", packageErr)
|
||||
}
|
||||
if _, statErr := os.Stat(destination); !os.IsNotExist(statErr) {
|
||||
t.Fatalf("oversized manifest left staging, stat error = %v", statErr)
|
||||
}
|
||||
}
|
||||
|
||||
func verifiedExpectation(t *testing.T, archivePath, version, entrypoint string) PackageExpectation {
|
||||
t.Helper()
|
||||
document, err := os.ReadFile(archivePath)
|
||||
if err != nil {
|
||||
t.Fatalf("read archive: %v", err)
|
||||
}
|
||||
hash := sha256.Sum256(document)
|
||||
return PackageExpectation{
|
||||
Size: int64(len(document)),
|
||||
SHA256: hex.EncodeToString(hash[:]),
|
||||
App: AppExpectation{
|
||||
ID: "test-app",
|
||||
Version: version,
|
||||
Channel: "stable",
|
||||
MinOS: "windows-10",
|
||||
Architecture: "amd64",
|
||||
Entrypoint: entrypoint,
|
||||
RequiresAdmin: false,
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
func validAppManifest(version, entrypoint string) []byte {
|
||||
return []byte(`{"schema_version":1,"id":"test-app","name":"Test App","vendor":"SoftBox","version":"` + version + `","channel":"stable","min_os":"windows-10","architecture":"amd64","entrypoint":"` + entrypoint + `","working_directory":".","product_id":"test-product","supports_trial":false,"requires_admin":false,"data_policy":"local-app-data","update_policy":"managed-by-softbox"}`)
|
||||
}
|
||||
@@ -33,6 +33,24 @@ type endOfCentralDirectory struct {
|
||||
func (extractor Extractor) openAndScanArchive(
|
||||
zipPath string,
|
||||
expectedPackageSize int64,
|
||||
) (*os.File, int64, error) {
|
||||
file, size, err := extractor.openArchiveFile(zipPath, expectedPackageSize)
|
||||
if err != nil {
|
||||
return nil, 0, err
|
||||
}
|
||||
if err := extractor.scanOpenedArchive(file, size); err != nil {
|
||||
_ = file.Close()
|
||||
return nil, 0, err
|
||||
}
|
||||
return file, size, nil
|
||||
}
|
||||
|
||||
// openArchiveFile opens the completed package once and proves the path still
|
||||
// names that same ordinary file. Later verification and parsing must retain
|
||||
// this handle rather than reopening zipPath.
|
||||
func (extractor Extractor) openArchiveFile(
|
||||
zipPath string,
|
||||
expectedPackageSize int64,
|
||||
) (*os.File, int64, error) {
|
||||
if err := extractor.limits.validate(); err != nil {
|
||||
return nil, 0, err
|
||||
@@ -64,6 +82,17 @@ func (extractor Extractor) openAndScanArchive(
|
||||
if !info.Mode().IsRegular() {
|
||||
return closeWithError(fmt.Errorf("%w: opened package is not a regular file", ErrInvalidArchive))
|
||||
}
|
||||
if !os.SameFile(pathInfo, info) {
|
||||
return closeWithError(fmt.Errorf("%w: package changed while opening", ErrInvalidArchive))
|
||||
}
|
||||
pathInfoAfterOpen, err := os.Lstat(zipPath)
|
||||
if err != nil {
|
||||
return closeWithError(fmt.Errorf("%w: recheck package: %v", ErrInvalidArchive, err))
|
||||
}
|
||||
if pathInfoAfterOpen.Mode()&os.ModeSymlink != 0 || !pathInfoAfterOpen.Mode().IsRegular() ||
|
||||
!os.SameFile(info, pathInfoAfterOpen) {
|
||||
return closeWithError(fmt.Errorf("%w: package changed while opening", ErrInvalidArchive))
|
||||
}
|
||||
size := info.Size()
|
||||
if size != expectedPackageSize {
|
||||
return closeWithError(fmt.Errorf(
|
||||
@@ -81,12 +110,43 @@ func (extractor Extractor) openAndScanArchive(
|
||||
extractor.limits.MaxArchiveBytes,
|
||||
))
|
||||
}
|
||||
if err := scanCentralDirectory(file, size, extractor.limits); err != nil {
|
||||
return closeWithError(err)
|
||||
}
|
||||
return file, size, nil
|
||||
}
|
||||
|
||||
func (extractor Extractor) scanOpenedArchive(file *os.File, expectedPackageSize int64) error {
|
||||
if file == nil {
|
||||
return fmt.Errorf("%w: package handle is nil", ErrInvalidArchive)
|
||||
}
|
||||
if err := extractor.limits.validate(); err != nil {
|
||||
return err
|
||||
}
|
||||
info, err := file.Stat()
|
||||
if err != nil {
|
||||
return fmt.Errorf("%w: stat package before ZIP scan: %v", ErrInvalidArchive, err)
|
||||
}
|
||||
if !info.Mode().IsRegular() {
|
||||
return fmt.Errorf("%w: opened package is not a regular file", ErrInvalidArchive)
|
||||
}
|
||||
size := info.Size()
|
||||
if size != expectedPackageSize {
|
||||
return fmt.Errorf(
|
||||
"%w: got %d, expected %d",
|
||||
ErrArchiveSizeMismatch,
|
||||
size,
|
||||
expectedPackageSize,
|
||||
)
|
||||
}
|
||||
if size > extractor.limits.MaxArchiveBytes {
|
||||
return fmt.Errorf(
|
||||
"%w: got %d, limit %d",
|
||||
ErrArchiveTooLarge,
|
||||
size,
|
||||
extractor.limits.MaxArchiveBytes,
|
||||
)
|
||||
}
|
||||
return scanCentralDirectory(file, size, extractor.limits)
|
||||
}
|
||||
|
||||
func scanCentralDirectory(file *os.File, size int64, limits Limits) error {
|
||||
end, err := findEndOfCentralDirectory(file, size)
|
||||
if err != nil {
|
||||
|
||||
@@ -64,6 +64,15 @@ func NewInstalledAppStore(appsRoot string) *InstalledAppStore {
|
||||
return &InstalledAppStore{appsRoot: appsRoot}
|
||||
}
|
||||
|
||||
// EnsureAppRoot creates and validates the real apps/<id> directory used by an
|
||||
// installer transaction. It does not write an installed-app record.
|
||||
func (store *InstalledAppStore) EnsureAppRoot(appID string) (string, error) {
|
||||
store.mu.Lock()
|
||||
defer store.mu.Unlock()
|
||||
|
||||
return store.ensureAppRoot(appID)
|
||||
}
|
||||
|
||||
// Write validates and atomically replaces one installed-app.json.
|
||||
func (store *InstalledAppStore) Write(record InstalledApp) error {
|
||||
store.mu.Lock()
|
||||
@@ -413,7 +422,11 @@ func replaceInstalledAppFile(directory, target, backup string, document []byte)
|
||||
}
|
||||
if movedTarget || hadBackup {
|
||||
if err := os.Remove(backup); err != nil && !os.IsNotExist(err) {
|
||||
return fmt.Errorf("remove installed app backup: %w", err)
|
||||
// The new target is already atomically active. Reporting a cleanup
|
||||
// failure here would make callers roll back a healthy current
|
||||
// directory while this record already names the new version. Keep the
|
||||
// regular recovery backup for a later successful replacement instead.
|
||||
return nil
|
||||
}
|
||||
}
|
||||
return nil
|
||||
|
||||
@@ -47,7 +47,7 @@ SoftBox 软件盒子是一个使用 Go + Gio 开发的 Windows 桌面客户端,
|
||||
|
||||
## 当前阶段
|
||||
|
||||
当前项目已完成 Phase 0～2、T-301 与审核整改 `T-604`～`T-614`。Windows 安全路径阻断项、图标缓存资源边界、后台结果回 UI 线程的事件接线、双适配器交互契约、`VisibleItems` 快照生命周期、双端 Gio shell 职责拆分、unsafe cache 安全诊断/runbook、ZIP 中央目录/EOCD(含 ZIP64)预扫描、安装文件/目录/journal 的代码层耐久顺序以及 Catalog canonicalization/签名静态 corpus 均已关闭;下一步正式落成 T-302。物理断电、文件锁与杀毒软件干扰验证仍后置到 T-302/T-601。
|
||||
当前项目已完成 Phase 0～2、T-301、T-302 与审核整改 `T-604`～`T-614`。Windows 安全路径阻断项、图标缓存资源边界、后台结果回 UI 线程的事件接线、双适配器交互契约、`VisibleItems` 快照生命周期、双端 Gio shell 职责拆分、unsafe cache 安全诊断/runbook、ZIP 中央目录/EOCD(含 ZIP64)预扫描、安装文件/目录/journal 的代码层耐久顺序、Catalog canonicalization/签名静态 corpus，以及同句柄 Catalog size/SHA→严格 app.json→staging/switch/回滚安装链均已关闭;下一步正式落成 T-303。物理断电、文件锁与杀毒软件干扰验证保留到 T-601 发布前环境验证。
|
||||
|
||||
优先路径:
|
||||
|
||||
@@ -55,7 +55,7 @@ SoftBox 软件盒子是一个使用 Go + Gio 开发的 Windows 桌面客户端,
|
||||
2. 已完成 Phase 1:清单验签、ZIP 安全解压、原子切换回滚原型。
|
||||
3. 已完成 Phase 2 与 T-301:清单/列表/详情/图标缓存 + 可恢复下载队列。
|
||||
4. 已完成 T-604:modern/Win7 workspace 与 Gio 版本解析彻底隔离。
|
||||
5. 已完成 T-606～T-614:图标缓存资源边界、UI 线程事件接线、双 Gio 适配器交互契约、`VisibleItems` generation 生命周期、双端 `shell.go` 同 package 镜像职责拆分、unsafe cache 诊断/人工恢复指引、ZIP 中央目录/EOCD 预扫描、安装耐久顺序和 Catalog 静态签名向量;下一步正式落成并执行 T-302,再继续 T-303 与 Phase 4-6。T-302/T-601 仍须补真实 Windows 环境的断电/干扰注入。
|
||||
5. 已完成 T-606～T-614:图标缓存资源边界、UI 线程事件接线、双 Gio 适配器交互契约、`VisibleItems` generation 生命周期、双端 `shell.go` 同 package 镜像职责拆分、unsafe cache 诊断/人工恢复指引、ZIP 中央目录/EOCD 预扫描、安装耐久顺序和 Catalog 静态签名向量;已完成 T-302:已验签 Catalog 选择与同句柄 size/SHA、严格 app.json、安全 staging/switch/健康与记录写回滚链路。下一步正式落成并执行 T-303,再继续 Phase 4-6。T-601 仍须补真实 Windows 环境的断电/干扰注入。
|
||||
|
||||
## 领取任务规则
|
||||
|
||||
|
||||
@@ -158,7 +158,7 @@ T-301 下载队列:
|
||||
- cancel 一旦先于 completion 取得线性化点,即使 body close/sync 报错也记录后继续精确清理;若 completion 先完成,后续 cancel 明确拒绝。known-total 完整 part 在同进程 resume/retry 与启动恢复中都直接 finalize,不发送 offset==total 的 Range。
|
||||
- 写入句柄的文件身份贯穿 sync/close 与 rename 前后核对,防止活跃 `.part` 路径被替换后发布错误文件。崩溃恢复对账 metadata、part、final 三份事实:完整 part 可 finalize,已 rename 的 final 可补 completed metadata;缺 final 的 completed、part+final、超出 expected/unknown 上限均 fail closed。
|
||||
- 事件投递失败通过 `OnObserverError` 显式报告,不改变 durable transfer 结果;application/UI 启动或重连后用 `Queue.Tasks()` 对账终态,避免 DownloadCompleted 等一次性通知丢失后永久停链。
|
||||
- DownloadCompleted 仅证明传输字节完整落盘。下载元数据和 `.download` 可被本地篡改,T-302 的 `application.InstallService` 不得把它们当信任根,而是接收已验签/过滤 Catalog `Entry` + architecture，确认其与 `App.Packages[architecture]` 精确对应。它将该 Catalog size/SHA-256 交给 `Extractor.ExtractVerifiedFile`，后者以同一打开的普通完成文件先 size、再 SHA-256、再 ZIP 预扫描/解析；package `signature` 仅由外层 Catalog 签名覆盖，当前没有独立包级验签域。
|
||||
- DownloadCompleted 仅证明传输字节完整落盘。下载元数据和 `.download` 可被本地篡改,T-302 的 `core/application/install.InstallService` 不得把它们当信任根,而是接收已验签/过滤 Catalog `Entry` + architecture，确认其与 `App.Packages[architecture]` 精确对应。它将该 Catalog size/SHA-256 交给 `Extractor.ExtractVerifiedFile`，后者以同一打开的普通完成文件先 size、再 SHA-256、再 ZIP 预扫描/解析；package `signature` 仅由外层 Catalog 签名覆盖，当前没有独立包级验签域。
|
||||
|
||||
### 4.3 事件模型
|
||||
|
||||
@@ -185,7 +185,7 @@ Phase 1 原子切换原型把 `install-transaction.json` 与目录现实共同
|
||||
|
||||
T-613 已把该状态机的代码层耐久顺序收敛为:payload 的 CRC/长度检查后 `Sync`/`Close` → staging 子目录到根及其父目录同步 → prepared journal 的临时文件 `Sync`/`Close` 与 root 栅栏 → 每次目录 rename 的 root 栅栏与下一 phase journal → committed journal 的 root 栅栏 → backup/journal 清理的 root 栅栏。所有栅栏通过 installer 内部接口复用;非 Windows 使用目录 `File.Sync`,Windows 用 Win7 已有的 `CreateFile(FILE_FLAG_BACKUP_SEMANTICS)` 读写目录句柄和 `FlushFileBuffers`,失败一律 fail closed。测试可注入失败并验证状态机保留可恢复 journal,但这仍不是物理掉电证明。
|
||||
|
||||
真实断电时的硬件/驱动缓存、杀毒软件/文件锁干扰和目标文件系统行为仍需 T-302/T-601 在 Windows VM/真机做故障注入,当前结论不替代硬件级断电验证。
|
||||
真实断电时的硬件/驱动缓存、杀毒软件/文件锁干扰和目标文件系统行为仍需 T-601 在 Windows VM/真机做故障注入；T-302 的代码级链路与单元测试不替代硬件级断电验证。
|
||||
|
||||
盒子自更新由独立 `SoftBoxUpdater.exe` 完成(传入 PID、暂存目录、目标目录;等待退出→备份→切换→启动新版→失败恢复)。
|
||||
|
||||
|
||||
+2
-2
@@ -42,13 +42,13 @@
|
||||
|
||||
#### Phase 1 交叉审核加固
|
||||
|
||||
Phase 1 安全整改按 `docs/review/phase1-security-review.md` 的交叉复核定稿顺序串行落成。T-605、T-612、T-613 与 T-614 已关闭;T-613 建立文件、目录和 journal 的代码层耐久顺序,T-614 冻结 Catalog canonicalization/签名静态 corpus 与客户端拒绝规则。下一步按路线图正式落成并执行 T-302;物理断电验证仍后置到 T-302/T-601。
|
||||
Phase 1 安全整改按 `docs/review/phase1-security-review.md` 的交叉复核定稿顺序串行落成。T-605、T-612、T-613 与 T-614 已关闭;T-613 建立文件、目录和 journal 的代码层耐久顺序,T-614 冻结 Catalog canonicalization/签名静态 corpus 与客户端拒绝规则。T-302 已将这些原型整合到同句柄 Catalog size/SHA、严格 app.json、安全 staging/switch/回滚的安装 use case；物理断电验证保留到 T-601。
|
||||
|
||||
| ID | 任务 | 依赖 | 验收要点 |
|
||||
| --- | --- | --- | --- |
|
||||
| T-605 | 统一 Windows 安全路径校验并封堵 ZIP 逃逸 | T-102, T-201, T-202, T-604 | Catalog/ZIP/installed-app 共用逐段 Windows 安全相对路径策略;拒绝尾随空格/点与 DOS 设备名;输出路径增加 destination 包含性兜底;原生 Windows 用例证明不写出 staging |
|
||||
| T-612 | 在 ZIP 打开前限制包大小与中央目录元数据 | T-605 | 已验签 Catalog size、已完成普通下载文件长度与同句柄 EOCD/ZIP64 预扫描一致;在 `zip.NewReader` 前限制原始包、中央目录与声明条目数 |
|
||||
| T-613 | 建立安装文件与目录事务耐久顺序 | T-612 | payload Sync、staging tree/journal/rename/remove 的目录栅栏;Windows `FlushFileBuffers` fail-closed;物理断电故障注入仍后置到 T-302/T-601 |
|
||||
| T-613 | 建立安装文件与目录事务耐久顺序 | T-612 | payload Sync、staging tree/journal/rename/remove 的目录栅栏;Windows `FlushFileBuffers` fail-closed;物理断电故障注入仍后置到 T-601 |
|
||||
| T-614 | 冻结 Catalog 规范化与签名跨实现测试向量 | T-613 | 静态 canonical bytes/Ed25519 test vectors 覆盖 Unicode、surrogate、`-0`/大整数、嵌套 signature 与 Base64;客户端不自举期望值,外部发布端可消费同一 corpus |
|
||||
|
||||
### Phase 2 · 清单与软件列表
|
||||
|
||||
+2
-2
@@ -153,7 +153,7 @@ T-102 Phase 1 原型进一步固定:
|
||||
- ZIP 名称只接受 UTF-8 `/` 分隔的规范 Windows 安全相对路径;逐段拒绝反斜杠、盘符、冒号/NTFS ADS、NUL/控制字符、Windows 禁止字符、`.`/`..`、首尾 ASCII 空格、尾随句点、DOS 设备名及大小写折叠后的重复输出路径。
|
||||
- 顶层只允许必需的 `app.json`、可选 `files.json` 与 `payload/`;只把 `payload/` 内容写入全新的 staging。
|
||||
- 拒绝符号链接、设备/管道等特殊文件和加密条目。
|
||||
- T-302 的 `application.InstallService` 只接收已验签、严格解析并按目标过滤后的 Catalog `Entry` + architecture 与 `.download` 候选路径。它必须确认 entry/package 与 `App.Packages[architecture]` 精确对应；不得从 T-301 task、`DownloadCompleted` payload 或本地 metadata 取得 app/version/size/hash。外层 Catalog Ed25519 签名覆盖嵌套 package 的 `size`、`sha256` 与 `signature` 文本；当前协议未定义 package `signature` 的独立待签名字节/公钥域，客户端不得臆造第二套包级验签。
|
||||
- T-302 的 `core/application/install.InstallService` 只接收已验签、严格解析并按目标过滤后的 Catalog `Entry` + architecture 与 `.download` 候选路径。它必须确认 entry/package 与 `App.Packages[architecture]` 精确对应；不得从 T-301 task、`DownloadCompleted` payload 或本地 metadata 取得 app/version/size/hash。外层 Catalog Ed25519 签名覆盖嵌套 package 的 `size`、`sha256` 与 `signature` 文本；当前协议未定义 package `signature` 的独立待签名字节/公钥域，客户端不得臆造第二套包级验签。
|
||||
- `Extractor.ExtractVerifiedFile` 必须接收该 Catalog package 的 `size`、`sha256` 与 app identity expectation。它以一次 `Lstat → open → fstat → Lstat` 取得普通 `.download` 文件，并在**同一打开句柄**上先精确核对 `expectedPackageSize`、再计算/常量时间比较 SHA-256；任一失败时不得构造 ZIP reader、读取 app.json 或创建 staging。T-301 的 known-total 完成文件已经以 Catalog size 限长，但 T-302 仍须执行上述重新对账，不能信任可篡改的下载 metadata。
|
||||
- 构造 `zip.Reader` 前只读取文件尾部至多 65,557 字节以定位 EOCD,并按需读取固定的 ZIP64 locator/EOCD 记录;校验单磁盘、中央目录 offset/size/entries 的边界及 entries/中央目录大小硬上限。当前默认上限为:原始包 4 GiB、中央目录 64 MiB、10,000 个条目、总展开 4 GiB、单条及总体压缩比 200:1。大小不一致、原始包超限、中央目录超限、声明条目超限分别保留 `ErrArchiveSizeMismatch`、`ErrArchiveTooLarge`、`ErrCentralDirectoryTooLarge`、`ErrTooManyEntries` 错误链;格式、截断、跨盘或不一致 ZIP64 归入 `ErrInvalidArchive`。
|
||||
- SHA-256 通过后，预扫描继续使用**同一文件句柄**和已核对的长度创建 `zip.NewReader`;完整中央目录/路径/entrypoint/类型/CRC/展开量预检仍是第二道防线。合法 ZIP64 被支持,不因 32 位 EOCD 哨兵值误拒绝。T-302 按真实包体分布复核上述暂定限额后再冻结。
|
||||
@@ -218,7 +218,7 @@ T-613 为该原型建立了 fail-closed 的耐久顺序:每个 payload 先完成
|
||||
|
||||
T-302 在 Switcher 的 health 阶段先运行必需的注入 health check，再原子写入新 `installed-app.json`;health 或记录写失败都必须触发既有 rollback，使旧 current/记录保持可用。只有 health 与记录均成功后才写 committed 并清理 backup/journal。
|
||||
|
||||
这些栅栏与注入失败测试只证明代码层面的调用顺序和 fail-closed 行为,不证明断电后硬件/驱动缓存、网络文件系统、文件锁或杀毒软件的物理表现。T-302/T-601 仍须在目标 Windows VM/真机执行断电与干扰故障注入。
|
||||
这些栅栏与注入失败测试只证明代码层面的调用顺序和 fail-closed 行为,不证明断电后硬件/驱动缓存、网络文件系统、文件锁或杀毒软件的物理表现。T-302 已完成代码整合；T-601 仍须在目标 Windows VM/真机执行断电与干扰故障注入。
|
||||
|
||||
### 2.6 下载任务元数据 download-task.json(本地)
|
||||
|
||||
|
||||
@@ -13,22 +13,22 @@
|
||||
## 当前快照
|
||||
|
||||
- 日期:2026-07-18
|
||||
- 阶段:Phase 2 已完成(T-201～T-204);Phase 3 的 T-301 可恢复下载队列已完成;审核整改 T-604～T-614 已完成;T-302 安装流程整合已正式落成、待领取并执行
|
||||
- 阶段:Phase 2 已完成(T-201～T-204);Phase 3 的 T-301 可恢复下载队列与 T-302 安装流程整合已完成;审核整改 T-604～T-614 已完成;下一步应正式落成并执行 T-303
|
||||
- 技术栈:根 Go 1.25 workspace 只纳入 core/app-modern,`app-win7/go.work` 独立纳入 core/app-win7;版本闸门证明 modern Gio v0.10.1 与 win7 Gio v0.6.0 不交叉解析
|
||||
- 生产代码:core 已有 Catalog/本地状态/存储、共享 Windows 安全相对路径策略与静态跨实现 canonicalization/Ed25519 vector corpus(拒绝非法 surrogate、`-0` 和非唯一 Base64 signature,大整数保持 token)、安全 ZIP 解压/回滚原型(Extractor 在同一普通文件句柄上核对 expected Catalog size 后有界预扫 EOCD/ZIP64、中央目录与条目数,每个 payload Sync/Close 后同步 staging tree 及父目录;transaction/switch/rollback/recovery 的 journal、rename、清理经统一 fail-closed 耐久栅栏,Windows 使用目录句柄 FlushFileBuffers)、发布稳定只读 generation 的无 IO 软件列表模型、按 key in-flight + 流式有界读取 + 32 MiB/256-key LRU 的可信图标缓存、图标 Load/Decode 事件发布用例、有界 application event relay,以及默认并发 2 的持久可恢复下载队列;modern/win7 主循环已接 relay/Invalidate,AppShell 已实现搜索/分类/视图、惰性列表、详情右栏、完整图标失败 identity 生命周期与仅 `unsafe_cache` 可见的安全 locator/人工恢复提示,并按 root/header/catalog/detail/style 同 package 镜像职责拆文件
|
||||
- 测试:core 覆盖 Catalog 静态 canonicalization/Ed25519 vectors、非法 surrogate/`-0`/Base64 fail-closed、列表快照 generation/零复制、SemVer/12 状态、本地安装记录、Windows dot-space/设备名/Unicode 折叠路径攻击、ZIP destination 包含性与 EOCD/ZIP64 原始包/中央目录/条目数预扫描、payload/staging tree/journal/rename/rollback/recovery/cleanup 耐久顺序及错误注入、Windows 原生目录 `FlushFileBuffers`、图标并发/取消/读取边界/LRU、真实目录/symlink fail-closed 与 cache→`unsafe_cache` event、relay 背压与关闭、下载并发/暂停/取消/重试/Range/断连/恢复/事件失败与文件身份替换;两个 app 覆盖 Editor/视图/分类/行/恢复/关闭接线、500 项 viewport、AppID 控件与分类控件生命周期、详情上下文、空状态语义、UI drain 前后、图标失败身份生命周期与 `unsafe_cache` 详情语义;安装恢复矩阵保持通过
|
||||
- 生产代码:core 已有 Catalog/本地状态/存储、共享 Windows 安全相对路径策略与静态跨实现 canonicalization/Ed25519 vector corpus(拒绝非法 surrogate、`-0` 和非唯一 Base64 signature,大整数保持 token)、安全 ZIP 解压/回滚原型及 T-302 安装 use case(`core/application/install.InstallService` 只取已过滤 Catalog entry + architecture,`Extractor.ExtractVerifiedFile` 在同一普通文件句柄按 size→SHA-256→EOCD/ZIP64→严格 app.json→安全 staging 的顺序处理,每个实际 payload 文件 hash 写入 installed-app;health 或记录写失败经 Switcher 回滚),transaction/switch/rollback/recovery 的 journal、rename、清理经统一 fail-closed 耐久栅栏,Windows 使用目录句柄 FlushFileBuffers)、发布稳定只读 generation 的无 IO 软件列表模型、按 key in-flight + 流式有界读取 + 32 MiB/256-key LRU 的可信图标缓存、图标 Load/Decode 事件发布用例、有界 application event relay,以及默认并发 2 的持久可恢复下载队列;modern/win7 主循环已接 relay/Invalidate,AppShell 已实现搜索/分类/视图、惰性列表、详情右栏、完整图标失败 identity 生命周期与仅 `unsafe_cache` 可见的安全 locator/人工恢复提示,并按 root/header/catalog/detail/style 同 package 镜像职责拆文件
|
||||
- 测试:core 覆盖 Catalog 静态 canonicalization/Ed25519 vectors、非法 surrogate/`-0`/Base64 fail-closed、列表快照 generation/零复制、SemVer/12 状态、本地安装记录、Windows dot-space/设备名/Unicode 折叠路径攻击、ZIP destination 包含性与 EOCD/ZIP64 原始包/中央目录/条目数预扫描、T-302 同句柄 package size/SHA、严格/有界 app.json、payload hash 记录、Catalog 选择拒绝、transaction recovery、health/记录写失败回滚、payload/staging tree/journal/rename/rollback/recovery/cleanup 耐久顺序及错误注入、Windows 原生目录 `FlushFileBuffers`、图标并发/取消/读取边界/LRU、真实目录/symlink fail-closed 与 cache→`unsafe_cache` event、relay 背压与关闭、下载并发/暂停/取消/重试/Range/断连/恢复/事件失败与文件身份替换;两个 app 覆盖 Editor/视图/分类/行/恢复/关闭接线、500 项 viewport、AppID 控件与分类控件生命周期、详情上下文、空状态语义、UI drain 前后、图标失败身份生命周期与 `unsafe_cache` 详情语义;安装恢复矩阵保持通过
|
||||
- 数据:`schemas/` 已有 manifest/app.json/installed-app.json/download-task.json v1 Schema并注明 Windows 路径运行时权威规则;`testdata/catalog/` 有公开虚构清单样例和 v1 静态 canonicalization/Ed25519 corpus;`testdata/zip/` 与 `testdata/download/` 记录运行时生成的攻击/传输矩阵
|
||||
- 标准启动路径:`./init.sh` / `./init.ps1`(同步依赖、执行完整 Phase 0 闸门、打印双目标构建命令)
|
||||
- 标准验证路径:`bash scripts/verify_phase0.sh` / `./scripts/verify_phase0.ps1`
|
||||
- 版本管理:git 已初始化,main 分支,远端 origin 为 Gitea `opc/soft_quay`;harness 文档已提交
|
||||
- 当前 blocker:无;T-614 已以静态 corpus 冻结客户端 Catalog canonicalization/签名行为,外部 `softbox-catalog` 消费 corpus 的 CI 证据仍需跨仓库协调,但不阻止落成 T-302。物理断电、文件锁/杀毒软件干扰仍需 T-302/T-601 的目标 Windows VM/真机故障注入
|
||||
- 当前 blocker:无;T-614 已以静态 corpus 冻结客户端 Catalog canonicalization/签名行为,外部 `softbox-catalog` 消费 corpus 的 CI 证据仍需跨仓库协调,但不阻止 T-303。物理断电、文件锁/杀毒软件干扰仍需 T-601 的目标 Windows VM/真机故障注入
|
||||
|
||||
## 当前目录要点
|
||||
|
||||
| 路径 | 状态 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `docs/` | 已有 | harness coding 文档集(本次初始化完成) |
|
||||
| `docs/tasks/` | 已有 | Phase 0～2、T-301 与 T-604～T-614 已完成;T-302 安装流程整合已落成且可领取 |
|
||||
| `docs/tasks/` | 已有 | Phase 0～2、T-301、T-302 与 T-604～T-614 已完成;下一步按路线图落成 T-303 失败处理与磁盘预检查任务 |
|
||||
| `scripts/` | 已有 | harness 治理、core 边界、Go 版本检查与 Phase 0 双平台验证入口 |
|
||||
| `core/` | 已建 | Go 1.20 兼容;已有正式 Catalog、本地状态/存储、共享 Windows safepath、列表模型、有界并发图标缓存、图标事件/relay、可恢复下载队列与 Phase 1 安装安全原型 |
|
||||
| `app-modern/` | 已建 | Go 1.25.0 + Gio v0.10.1;Modern AppShell 已接入虚拟列表、详情、图标事件 drain/过期拒绝和内存 ImageOp,并拆为五类 shell 职责文件 |
|
||||
@@ -40,9 +40,9 @@
|
||||
|
||||
任务状态以 `docs/tasks/` 各任务文件 frontmatter 的 `status` 为准。本节只写项目级摘要:
|
||||
|
||||
- 已完成:Phase 0 的 `T-001`～`T-004`;Phase 1 的 `T-101`、`T-102`、`T-103`;Phase 2 的 `T-201`～`T-204`;Phase 3 的 `T-301`;审核整改 `T-604`～`T-614`。
|
||||
- 已完成:Phase 0 的 `T-001`～`T-004`;Phase 1 的 `T-101`、`T-102`、`T-103`;Phase 2 的 `T-201`～`T-204`;Phase 3 的 `T-301`、`T-302`;审核整改 `T-604`～`T-614`。
|
||||
- 正在进行:无。
|
||||
- 下一个可领取任务:T-302（依赖 T-301/T-102/T-103 均已完成）。T-302/T-601 的物理断电与干扰故障注入仍保留为发布前环境验证。
|
||||
- 下一个可领取任务:暂无；应按 Phase 3 路线图先将 T-303 失败处理与磁盘预检查正式落成任务文件，再领取。T-601 的物理断电与干扰故障注入仍保留为发布前环境验证。
|
||||
|
||||
## 当前可运行内容
|
||||
|
||||
|
||||
+12
-6
@@ -3,12 +3,12 @@ id: T-302
|
||||
title: 安装流程整合
|
||||
phase: 3
|
||||
deps: [T-301, T-102, T-103]
|
||||
status: TODO
|
||||
status: DONE
|
||||
created: 2026-07-18
|
||||
issue: null
|
||||
context_ref: null
|
||||
context_ref: 6575c9ad9b997366514277a925196b2e52f16f75
|
||||
claim_branch: null
|
||||
work_branch: null
|
||||
work_branch: agent/codex/T-302
|
||||
write_paths:
|
||||
- docs/tasks/T-302.md
|
||||
- core/application/
|
||||
@@ -16,6 +16,8 @@ write_paths:
|
||||
- core/storage/
|
||||
- docs/api.md
|
||||
- docs/04-architecture.md
|
||||
- docs/00-ai-start-here.md
|
||||
- docs/06-tasks.md
|
||||
- docs/current-state.md
|
||||
---
|
||||
|
||||
@@ -27,7 +29,7 @@ T-301 只能把网络字节可靠地落为隔离的 `.download`;下载任务元
|
||||
|
||||
## 方案
|
||||
|
||||
1. 在 `core/application` 落地 `InstallService`：请求包含已过滤的 `catalog.Entry`、目标 architecture 和 `.download` 路径。服务必须拒绝不可安装 entry、缺失 package、architecture 与 `App.Packages[architecture]` 不一致的选择；不得从 `downloader.Task`、`DownloadCompletedPayload` 或本地 metadata 重新取得 app/version/size/hash。
|
||||
1. 在 `core/application/install` 落地 `InstallService`：请求包含已过滤的 `catalog.Entry`、目标 architecture 和 `.download` 路径。服务必须拒绝不可安装 entry、缺失 package、architecture 与 `App.Packages[architecture]` 不一致的选择；不得从 `downloader.Task`、`DownloadCompletedPayload` 或本地 metadata 重新取得 app/version/size/hash。该 application 子包独立于被 Catalog 图标投递依赖的父包，避免反向 import cycle。
|
||||
2. 在 `core/installer` 增加经过验证的包提取入口。它以一次 `Lstat → open → fstat → Lstat` 得到普通文件句柄，先确认实际长度精确等于 Catalog size、再以**同一文件句柄**计算 SHA-256，并以常量时间比较 Catalog hash；哈希不符时不得构造 `zip.Reader`、读取 `app.json` 或创建 staging。随后仍以同一句柄完成 EOCD/ZIP64/中央目录预扫描和 `zip.Reader` 构造，不能按路径重新打开。
|
||||
3. 安全读取 ZIP 根目录唯一的 `app.json`（最大 1 MiB，严格 JSON、无未知字段/尾随值），校验 v1 的全部字段与共享 Windows 安全相对路径规则。身份字段必须与 Catalog 选择一致：`id`、`version`、`channel`、`min_os`、`architecture`、`entrypoint`、`requires_admin`；其余 v1 常量和值也必须符合 `schemas/app.schema.json`。只有通过比对后，才复用既有两阶段 ZIP 检查把 `payload/` 解压到全新的 `apps/<id>/staging`。
|
||||
4. 解压复制时为每个实际 payload 文件计算 size/SHA-256，作为 `ExtractResult` 的已观察文件清单。`InstallService` 将此清单写入 `installed-app.json`，不信任或依赖可选的 `files.json` 作为新的信任根；保留 v1 `files.json` 的协议语义和后续修复功能边界。
|
||||
@@ -47,7 +49,7 @@ T-301 只能把网络字节可靠地落为隔离的 `.download`;下载任务元
|
||||
|
||||
- 不修改 Catalog 签名协议、Schema 或密钥；不为 nested package `signature` 虚构独立验签算法。外层已验签 Catalog 是本任务唯一的密码学身份来源。
|
||||
- 不做磁盘空间预检、程序占用/退出等待、面向 UI 的完整错误码映射或下载重试策略（T-303/T-401）；不强杀或自动启动包内程序。
|
||||
- 不做 Gio 安装面板、下载完成到安装调用的 UI 编排或物理断电/杀毒软件/文件锁故障注入。T-302 只提供无头 core use case；真实 Windows VM/真机故障注入仍由 T-302/T-601 发布前环境验证完成。
|
||||
- 不做 Gio 安装面板、下载完成到安装调用的 UI 编排或物理断电/杀毒软件/文件锁故障注入。T-302 只提供无头 core use case；真实 Windows VM/真机故障注入转入 T-601 发布前环境验证。
|
||||
- 不改变 `files.json` 的 v1/v1.1 协议或实现修复功能，不引入数据库、第三方包、Gio、Windows API 或 Go 1.21+ API。
|
||||
|
||||
## 协作约束
|
||||
@@ -58,4 +60,8 @@ T-301 只能把网络字节可靠地落为隔离的 `.download`;下载任务元
|
||||
|
||||
## 执行记录
|
||||
|
||||
- 2026-07-18:正式落成。冻结可信输入、同句柄 size/SHA/ZIP 顺序、严格 app.json 对齐、实际 payload 文件记录、health 内记录写入回滚语义和后续任务边界；待领取后执行基线验证与实现。
|
||||
- 2026-07-18:正式落成。冻结可信输入、同句柄 size/SHA/ZIP 顺序、严格 app.json 对齐、实际 payload 文件记录、health 内记录写入回滚语义和后续任务边界。
|
||||
- 2026-07-18:领取任务，基线为 `6575c9ad9b997366514277a925196b2e52f16f75`，工作分支 `agent/codex/T-302`；下一步运行统一初始化/完整基线，再开始实现。
|
||||
- 2026-07-18:基线通过：`./init.ps1` 完成治理、core 架构/Go 版本闸门、Go 1.20 core vet/test、modern/Win7 test/build 与 Python harness 校验。
|
||||
- 2026-07-18:实现 `core/application/install.InstallService`、同句柄 `Extractor.ExtractVerifiedFile`、严格且有 1 MiB 上限的 app.json 校验、payload 观测 hash 清单和 `InstalledAppStore.EnsureAppRoot`；Catalog 依赖父 application 包的既有图标投递链会产生 import cycle，因此 use case 放在独立 application 子包，未改变 Gio/UI 边界。
|
||||
- 2026-07-18:复核成功/size+hash+选择失败/严格 manifest/非普通文件/manifest 上限/transaction recovery/health 与记录写失败回滚；`go -C core vet ./...`、`go -C core test -count=1 ./...` 和 `go -C core test -count=10 ./installer ./application/install` 全部通过。真实 Windows 断电、文件锁/杀毒软件故障注入未在当前环境执行，保留为 T-601 发布前验证。
|
||||
|
||||
Reference in New Issue
Block a user