feat(packages): complete storage and VPM lifecycle

.config/dotnet-tools.json

@@ -0,0 +1,11 @@
+{
+  "version": 1,
+  "isRoot": true,
+  "tools": {
+    "vrchat.vpm.cli": {
+      "version": "0.1.28",
+      "commands": ["vpm"],
+      "rollForward": false
+    }
+  }
+}

.env.example

@@ -24,5 +24,6 @@ DELIVERY_HMAC_KEY=               # signs delivery URLs; generate: openssl rand -
 DELIVERY_BASE_URL=               # public delivery Worker origin, e.g. https://delivery.example.com
 STORAGE_FORMAT_VERSION=desync-uncompressed-sha256-v1 # delivery manifest format
 VPM_BASE_URL=                    # optional public API origin for buyer VPM indexes; routes return 503 when unset
+VPM_ALIAS_PUBLICATION_CATALOG_DATABASE_URL= # PostgreSQL workflow store for immutable VPM alias publications
 CAS_S3_READONLY_ACCESS_KEY_ID=   # B2 read-only keyID the Worker uses to fetch private chunks on cache miss
 CAS_S3_READONLY_SECRET_ACCESS_KEY= # B2 read-only applicationKey for the Worker

.gitignore

@@ -8,7 +8,7 @@
 /apps/web/.cloudflare.deploy.vars
 /apps/web/.wrangler
 /\.wrangler
-/services/delivery-worker/.wrangler
+/services/*/.wrangler
 node_modules
 *.md
 !README.md
@@ -55,8 +55,14 @@ convex/tsconfig.tsbuildinfo
 /apps/api/test-results
 /apps/api/test-results
 /apps/web/.tanstack
-/Verify/Native/
+/Verify/Native/*
+!/Verify/Native/transfer-helper/
+!/Verify/Native/transfer-helper/**
 /.volumes
+/.idea/
+/.orchestration/
+/TestResults/
+/longtail.csv
 
 # Licensed Streamline artwork is generated locally and must never be committed.
 /apps/web/src/icons/generated.tsx*

Verify/Native/transfer-helper/.gitignore

@@ -0,0 +1,3 @@
+/dist/
+/yucp-transfer-helper
+/yucp-transfer-helper.exe

Verify/Native/transfer-helper/README.md

@@ -0,0 +1,81 @@
+# YUCP transfer helper
+
+The helper downloads its own trusted releases through TUF.
+
+The importer supplies the initial signed root metadata.
+
+The helper rejects expired, rolled-back, oversized, or incorrectly signed metadata.
+
+Verified targets use versioned paths.
+
+The helper never overwrites an existing target.
+
+The helper verifies signed `FileTableShardV2` recipes.
+
+It reconstructs common files from the verified local chunk cache.
+
+Protected source recipes fail before the helper creates a staging tree.
+
+## Toolchain
+
+Use Go 1.26.5.
+
+The TUF client uses `go-tuf` v2.4.2.
+
+API reference: [go-tuf updater](https://pkg.go.dev/github.com/theupdateframework/go-tuf/v2/metadata/updater)
+
+## Build
+
+1. Run `go test ./...`.
+2. Run `go vet ./...`.
+3. Run `go build ./cmd/yucp-transfer-helper`.
+
+Use this production build command:
+
+```text
+go build -trimpath -ldflags="-s -w" -o dist/yucp-transfer-helper.exe ./cmd/yucp-transfer-helper
+```
+
+## Update command
+
+Use the `update` command with a pinned root and direct repository URLs.
+
+Remote URLs require HTTPS.
+
+Loopback tests can use HTTP.
+
+```text
+yucp-transfer-helper update \
+  --root <root-path> \
+  --metadata-url <metadata-url> \
+  --targets-url <targets-url> \
+  --metadata-cache <cache-path> \
+  --target <target-name> \
+  --destination <versioned-path> \
+  --trace-id <trace-id>
+```
+
+The command writes one JSON result to standard output.
+
+The result includes the trace identifier, target digest, byte length, cache state, and final path.
+
+## Reconstruct command
+
+Use `reconstruct` with a signed file-table shard and trusted signing key.
+
+The current profile reads uncompressed desync chunks from the local cache.
+
+The helper verifies encoded SHA-256 values and domain-separated logical digests.
+
+It publishes the staging tree only after all files pass verification.
+
+```text
+yucp-transfer-helper reconstruct \
+  --signed-shard <cose-file-table-shard> \
+  --public-key <ed25519-public-key-hex> \
+  --key-id <trusted-key-id> \
+  --chunk-cache <cache-root> \
+  --destination <new-staging-tree> \
+  --encoding-profile desync-uncompressed-sha256-v1 \
+  --trace-id <trace-id>
+```

Verify/Native/transfer-helper/cmd/yucp-local-tuf-repository/main.go

@@ -0,0 +1,189 @@
+package main
+
+import (
+	"crypto"
+	"crypto/ed25519"
+	"crypto/sha256"
+	"encoding/base64"
+	"encoding/json"
+	"flag"
+	"fmt"
+	"os"
+	"path/filepath"
+	"time"
+
+	"github.com/sigstore/sigstore/pkg/signature"
+	"github.com/theupdateframework/go-tuf/v2/metadata"
+	"github.com/yucp/transfer-helper/internal/tufrepository"
+)
+
+const (
+	helperTargetName = "helper/windows-amd64/yucp-transfer-helper.exe"
+	trustTargetName  = "package-install-trust.json"
+)
+
+type authority struct {
+	KeyID     string `json:"keyId"`
+	PublicKey string `json:"publicKey"`
+}
+
+type trustTarget struct {
+	MaterializationReceipt authority `json:"materializationReceipt"`
+	PackageInstall         authority `json:"packageInstall"`
+	SchemaVersion          int       `json:"schemaVersion"`
+}
+
+func main() {
+	output := flag.String("output", "", "local TUF repository output directory")
+	rootPath := flag.String("root", "", "pinned local TUF root path")
+	helperPath := flag.String("helper", "", "source-built Windows helper executable")
+	metadataVersion := flag.Int64(
+		"metadata-version",
+		0,
+		"monotonic local TUF metadata version",
+	)
+	installKeyID := flag.String("install-key-id", "", "package install signing key identifier")
+	installPublicKey := flag.String("install-public-key", "", "package install Ed25519 public key")
+	receiptKeyID := flag.String("receipt-key-id", "", "receipt signing key identifier")
+	receiptPublicKey := flag.String("receipt-public-key", "", "receipt Ed25519 public key")
+	flag.Parse()
+	if flag.NArg() != 0 {
+		fatal(fmt.Errorf("unexpected positional arguments"))
+	}
+	if err := generate(
+		*output,
+		*rootPath,
+		*helperPath,
+		*metadataVersion,
+		*installKeyID,
+		*installPublicKey,
+		*receiptKeyID,
+		*receiptPublicKey,
+	); err != nil {
+		fatal(err)
+	}
+}
+
+func generate(
+	output string,
+	rootPath string,
+	helperPath string,
+	metadataVersion int64,
+	installKeyID string,
+	installPublicKey string,
+	receiptKeyID string,
+	receiptPublicKey string,
+) error {
+	if !filepath.IsAbs(output) || !filepath.IsAbs(rootPath) || !filepath.IsAbs(helperPath) {
+		return fmt.Errorf("local TUF output, root, and helper paths must be absolute")
+	}
+	if metadataVersion < 1 {
+		return fmt.Errorf("local TUF metadata version must be positive")
+	}
+	requiredValues := []struct {
+		name  string
+		value string
+	}{
+		{"install key identifier", installKeyID},
+		{"install public key", installPublicKey},
+		{"receipt key identifier", receiptKeyID},
+		{"receipt public key", receiptPublicKey},
+	}
+	for _, required := range requiredValues {
+		if required.value == "" {
+			return fmt.Errorf("%s is required", required.name)
+		}
+	}
+	publicKeys := []struct {
+		name    string
+		encoded string
+	}{
+		{"install public key", installPublicKey},
+		{"receipt public key", receiptPublicKey},
+	}
+	for _, publicKey := range publicKeys {
+		decoded, err := base64.RawURLEncoding.DecodeString(publicKey.encoded)
+		if err != nil || len(decoded) != ed25519.PublicKeySize {
+			return fmt.Errorf("%s is invalid", publicKey.name)
+		}
+	}
+	rootBytes, err := os.ReadFile(rootPath)
+	if err != nil {
+		return fmt.Errorf("read pinned local TUF root: %w", err)
+	}
+	targetBytes, err := json.Marshal(trustTarget{
+		MaterializationReceipt: authority{
+			KeyID:     receiptKeyID,
+			PublicKey: receiptPublicKey,
+		},
+		PackageInstall: authority{
+			KeyID:     installKeyID,
+			PublicKey: installPublicKey,
+		},
+		SchemaVersion: 1,
+	})
+	if err != nil {
+		return fmt.Errorf("encode local package trust target: %w", err)
+	}
+	helperBytes, err := os.ReadFile(helperPath)
+	if err != nil {
+		return fmt.Errorf("read source-built helper: %w", err)
+	}
+	if len(helperBytes) < 1 || len(helperBytes) > 256*1024*1024 {
+		return fmt.Errorf("source-built helper length is invalid")
+	}
+	snapshotSigner, err := deterministicLocalSigner(metadata.SNAPSHOT)
+	if err != nil {
+		return err
+	}
+	targetsSigner, err := deterministicLocalSigner(metadata.TARGETS)
+	if err != nil {
+		return err
+	}
+	timestampSigner, err := deterministicLocalSigner(metadata.TIMESTAMP)
+	if err != nil {
+		return err
+	}
+	now := time.Now().UTC()
+	bundle, err := tufrepository.Build(tufrepository.Input{
+		MetadataVersion: metadataVersion,
+		Now:             now,
+		Root:            rootBytes,
+		Signers: tufrepository.OnlineSigners{
+			Snapshot:  snapshotSigner,
+			Targets:   targetsSigner,
+			Timestamp: timestampSigner,
+		},
+		SnapshotExpires: now.Add(7 * 24 * time.Hour),
+		Targets: []tufrepository.Target{
+			{Bytes: helperBytes, Name: helperTargetName},
+			{Bytes: targetBytes, Name: trustTargetName},
+		},
+		TargetsExpires:   now.Add(30 * 24 * time.Hour),
+		TimestampExpires: now.Add(24 * time.Hour),
+	})
+	if err != nil {
+		return fmt.Errorf("build local TUF repository: %w", err)
+	}
+	if bundle.RootVersion != 1 {
+		return fmt.Errorf("pinned local TUF root is not the expected test root")
+	}
+	return bundle.Write(output)
+}
+
+func deterministicLocalSigner(role string) (signature.Signer, error) {
+	seed := sha256.Sum256([]byte("YUCP transfer-helper TUF test key: " + role))
+	signer, err := signature.LoadSigner(
+		ed25519.NewKeyFromSeed(seed[:]),
+		crypto.Hash(0),
+	)
+	if err != nil {
+		return nil, fmt.Errorf("load local TUF %s signer: %w", role, err)
+	}
+	return signer, nil
+}
+
+func fatal(err error) {
+	_, _ = fmt.Fprintln(os.Stderr, err)
+	os.Exit(1)
+}