@synopackageland/cli 0.5.0 → 0.6.0

package/templates/native-go-delegate/backend/internal/delegate/files.go

@@ -0,0 +1,132 @@
+package delegate
+
+import (
+	"context"
+	"dsmapp/internal/filestation"
+	"io"
+	"os"
+	"path"
+	"strings"
+)
+
+type ListOptions = filestation.ListOptions
+type JobContext struct {
+	Client                          *Client
+	callExecutor                    func(context.Context, string, map[string]any, any) error
+	JobID, DelegationID, StagingDir string
+}
+
+func (j JobContext) Files() filestation.Files { return jobFiles{j} }
+
+type jobFiles struct{ JobContext }
+
+var _ filestation.Files = jobFiles{}
+
+const MaxDownloadBytes int64 = 64 << 20
+
+func (f jobFiles) call(ctx context.Context, op string, p map[string]any, out any) error {
+	if f.JobID == "" || f.DelegationID == "" {
+		return fail("invalid-request")
+	}
+	p["job_id"] = f.JobID
+	p["delegation_id"] = f.DelegationID
+	if f.callExecutor != nil {
+		return f.callExecutor(ctx, op, p, out)
+	}
+	return f.Client.Call(ctx, op, nil, p, out)
+}
+func (f jobFiles) List(ctx context.Context, p string, o ListOptions) (filestation.Page, error) {
+	var out filestation.Page
+	// The fixed executor registry accepts path only; do not invent wire options.
+	if o != (ListOptions{}) {
+		return out, fail("unsupported")
+	}
+	e := f.call(ctx, "files.list", map[string]any{"path": p}, &out)
+	if e == nil && (out.Files == nil || out.Offset != 0 || out.Total < len(out.Files)) {
+		e = fail("EXECUTOR_PROTOCOL")
+	}
+	return out, e
+}
+func (f jobFiles) Info(ctx context.Context, p string) (filestation.Entry, error) {
+	var out struct {
+		Files []filestation.Entry `json:"files"`
+	}
+	e := f.call(ctx, "files.info", map[string]any{"path": p}, &out)
+	if e != nil {
+		return filestation.Entry{}, e
+	}
+	if len(out.Files) != 1 || out.Files[0].Path != p {
+		return filestation.Entry{}, fail("EXECUTOR_PROTOCOL")
+	}
+	return out.Files[0], nil
+}
+func (f jobFiles) CreateFolder(ctx context.Context, p, n string) error {
+	return f.call(ctx, "files.createFolder", map[string]any{"path": p, "name": n}, nil)
+}
+func (f jobFiles) CheckPermission(ctx context.Context, p string) error {
+	return f.call(ctx, "files.checkPermission", map[string]any{"path": p}, nil)
+}
+func validName(n string) bool {
+	return n != "" && n != "." && n != ".." && len(n) <= 255 && !strings.ContainsAny(n, "/\\\x00\r\n")
+}
+func validPath(p string) bool {
+	return strings.HasPrefix(p, "/") && path.Clean(p) == p && !strings.ContainsAny(p, "\x00\r\n\\") && len(p) <= 4096
+}
+
+// Write consumes at most size+1 bytes into a random private staging file, then
+// asks the executor to create the destination without overwriting it. Cleanup
+// runs on refusals, read failures, cancellation and uncertain responses too.
+func (f jobFiles) Write(ctx context.Context, dir, name string, source io.Reader, size int64) error {
+	if !validPath(dir) || !validName(name) || size < 0 || size > MaxDownloadBytes || source == nil {
+		return fail("invalid-request")
+	}
+	if e := os.MkdirAll(f.StagingDir, 0700); e != nil {
+		return fail("STAGING_UNAVAILABLE")
+	}
+	info, e := os.Lstat(f.StagingDir)
+	if e != nil || !info.IsDir() || info.Mode().Perm()&0077 != 0 {
+		return fail("STAGING_UNAVAILABLE")
+	}
+	root, e := os.OpenRoot(f.StagingDir)
+	if e != nil {
+		return fail("STAGING_UNAVAILABLE")
+	}
+	defer root.Close()
+	// CreateTemp generates names internally and uses O_EXCL with mode 0600.
+	staged, e := os.CreateTemp(f.StagingDir, "write-")
+	if e != nil {
+		return fail("STAGING_UNAVAILABLE")
+	}
+	base := path.Base(staged.Name())
+	defer root.Remove(base)
+	defer staged.Close()
+	n, e := io.Copy(staged, io.LimitReader(contextReader{ctx, source}, size+1))
+	if e != nil {
+		if ctx.Err() != nil {
+			return fail("canceled")
+		}
+		return fail("STAGING_UNAVAILABLE")
+	}
+	if n != size {
+		return fail("limit-exceeded")
+	}
+	if e = staged.Sync(); e != nil {
+		return fail("STAGING_UNAVAILABLE")
+	}
+	if e = staged.Close(); e != nil {
+		return fail("STAGING_UNAVAILABLE")
+	}
+	return f.call(ctx, "files.write", map[string]any{"staging": base, "dest_dir": dir, "name": name}, nil)
+}
+
+type contextReader struct {
+	ctx context.Context
+	r   io.Reader
+}
+
+func (r contextReader) Read(p []byte) (int, error) {
+	if e := r.ctx.Err(); e != nil {
+		return 0, e
+	}
+	return r.r.Read(p)
+}

package/templates/native-go-delegate/backend/internal/delegate/retry.go

@@ -0,0 +1,106 @@
+package delegate
+
+import (
+	"context"
+	"errors"
+	"time"
+)
+
+const executorWaitLimit = 15 * time.Minute
+
+func (s *Service) clockNow() time.Time {
+	if s.now != nil {
+		return s.now()
+	}
+	return time.Now()
+}
+func (s *Service) waitExecutor(ctx context.Context, delay time.Duration) error {
+	if s.wait != nil {
+		return s.wait(ctx, delay)
+	}
+	timer := time.NewTimer(delay)
+	defer timer.Stop()
+	select {
+	case <-ctx.Done():
+		return ctx.Err()
+	case <-timer.C:
+		return nil
+	}
+}
+
+// Retry only failures that prove no executor connection was established. Once
+// connected, even an uncertain/partial write is terminal and never replayed.
+func (s *Service) callWaitingExecutor(ctx context.Context, id string, expires time.Time, op string, params map[string]any, out any) error {
+	var deadline time.Time
+	delay := 2 * time.Second
+	waiting := false
+	for {
+		if ctx.Err() != nil {
+			return fail("canceled")
+		}
+		now := s.clockNow()
+		if !expires.IsZero() && !now.Before(expires) {
+			return fail("DELEGATION_EXPIRED")
+		}
+		if waiting && !now.Before(deadline) {
+			return fail("EXECUTOR_UNAVAILABLE")
+		}
+		binding, err := s.Store.Delegation(ctx, id)
+		if err != nil {
+			return err
+		}
+		if binding.DelegationID != params["delegation_id"] {
+			return fail("invalid-request")
+		}
+		state, err := s.Store.Get(ctx, id)
+		if err != nil {
+			return err
+		}
+		if state.CancelRequested || state.PurgeRequested {
+			return fail("canceled")
+		}
+		callCtx := ctx
+		cancel := func() {}
+		if waiting {
+			callCtx, cancel = context.WithTimeout(ctx, deadline.Sub(now))
+		}
+		err = s.Client.Call(callCtx, op, nil, params, out)
+		cancel()
+		var dial *dialFailure
+		if !errors.As(err, &dial) {
+			if err == nil && waiting {
+				// A racing cancellation still wins in Store.Finish.
+				_ = s.Store.SetExecutorWaiting(ctx, id, false)
+			}
+			return err
+		}
+		if !waiting {
+			waiting = true
+			deadline = s.clockNow().Add(executorWaitLimit)
+			if err = s.Store.SetExecutorWaiting(ctx, id, true); err != nil {
+				return err
+			}
+		}
+		now = s.clockNow()
+		remaining := deadline.Sub(now)
+		if !expires.IsZero() && expires.Sub(now) < remaining {
+			remaining = expires.Sub(now)
+		}
+		if remaining <= 0 {
+			continue
+		}
+		pause := delay
+		if pause > remaining {
+			pause = remaining
+		}
+		if err = s.waitExecutor(ctx, pause); err != nil {
+			return fail("canceled")
+		}
+		if delay < 30*time.Second {
+			delay *= 2
+			if delay > 30*time.Second {
+				delay = 30 * time.Second
+			}
+		}
+	}
+}

package/templates/native-go-delegate/backend/internal/delegate/retry_test.go

@@ -0,0 +1,143 @@
+package delegate
+
+import (
+	"context"
+	"dsmapp/internal/background"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+)
+
+func absentExecutor(t *testing.T) *Client {
+	t.Helper()
+	dir, err := os.MkdirTemp("", "boot-")
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { os.RemoveAll(dir) })
+	return &Client{Socket: filepath.Join(dir, "s")}
+}
+
+func retryJob(t *testing.T, s *Service, expires time.Time) string {
+	t.Helper()
+	web := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { w.Write([]byte("download")) }))
+	t.Cleanup(web.Close)
+	data, _ := json.Marshal(DownloadInput{URL: web.URL, Dest: "/home", Name: "file"})
+	job, err := s.Store.SubmitDelegated(context.Background(), background.SubmitRequest{Key: "retry", Name: "file", Data: data, Submitter: background.Submitter{User: "alice", UID: "1205"}}, func(string) (background.DelegationBinding, error) {
+		return background.DelegationBinding{DelegationID: "grant", ExpiresAt: expires}, nil
+	}, func(background.DelegationBinding) { t.Error("unexpected rollback") })
+	if err != nil {
+		t.Fatal(err)
+	}
+	return job.ID
+}
+func retryClock(s *Service) *time.Time {
+	now := time.Now()
+	s.now = func() time.Time { return now }
+	s.wait = func(ctx context.Context, d time.Duration) error { now = now.Add(d); return ctx.Err() }
+	return &now
+}
+func assertJob(t *testing.T, s *Service, id string, state background.State, code string) {
+	t.Helper()
+	job, err := s.Store.Get(context.Background(), id)
+	if err != nil || job.State != state || job.ErrorCode != code {
+		t.Fatalf("job=%+v err=%v want %s/%s", job, err, state, code)
+	}
+}
+func TestExecutorAppearsAfterBootDelay(t *testing.T) {
+	s := service(t, absentExecutor(t))
+	now := retryClock(s)
+	start := *now
+	id := retryJob(t, s, now.Add(time.Hour))
+	var delays []time.Duration
+	writes := 0
+	ready := executor(t, func(q Request) string {
+		if q.Op == "files.write" {
+			writes++
+		}
+		return `{"ok":true,"result":{}}` + "\n"
+	})
+	s.wait = func(ctx context.Context, d time.Duration) error {
+		delays = append(delays, d)
+		*now = now.Add(d)
+		if now.Sub(start) >= 100*time.Second {
+			// The configured socket path itself appears late; client configuration stays fixed.
+			if err := os.Rename(ready.Socket, s.Client.Socket); err != nil {
+				t.Fatal(err)
+			}
+		}
+		out := rpc(t, s, "alice", "delegate.jobs.list", "{}")
+		list := out["data"].(map[string]any)["jobs"].([]any)
+		if list[0].(map[string]any)["state"] != "waiting_executor" {
+			t.Fatalf("not waiting: %v", out)
+		}
+		return ctx.Err()
+	}
+	if err := s.RunOnce(context.Background()); err != nil {
+		t.Fatal(err)
+	}
+	assertJob(t, s, id, background.StateSucceeded, "")
+	if writes != 1 {
+		t.Fatalf("writes=%d", writes)
+	}
+	want := []time.Duration{2, 4, 8, 16, 30, 30, 30}
+	if len(delays) != len(want) {
+		t.Fatal(delays)
+	}
+	for i, d := range want {
+		if delays[i] != d*time.Second {
+			t.Fatal(delays)
+		}
+	}
+}
+func TestExecutorWaitStopsAtFifteenMinutes(t *testing.T) {
+	s := service(t, absentExecutor(t))
+	now := retryClock(s)
+	start := *now
+	id := retryJob(t, s, now.Add(time.Hour))
+	// Revocation remains pending while the executor is absent.
+	_ = s.RunOnce(context.Background())
+	assertJob(t, s, id, background.StateFailed, "EXECUTOR_UNAVAILABLE")
+	if now.Sub(start) != 15*time.Minute {
+		t.Fatalf("wait=%s", now.Sub(start))
+	}
+	pending, err := s.Store.DelegationCleanup(context.Background())
+	if err != nil || len(pending) != 1 {
+		t.Fatalf("grant cleanup lost: %v %v", pending, err)
+	}
+}
+func TestExecutorWaitHonorsGrantExpiry(t *testing.T) {
+	s := service(t, absentExecutor(t))
+	now := retryClock(s)
+	start := *now
+	id := retryJob(t, s, now.Add(5*time.Second))
+	_ = s.RunOnce(context.Background())
+	assertJob(t, s, id, background.StateFailed, "DELEGATION_EXPIRED")
+	if now.Sub(start) != 5*time.Second {
+		t.Fatalf("expiry delayed: %s", now.Sub(start))
+	}
+}
+func TestAcceptedWriteIsNeverRetried(t *testing.T) {
+	writes := 0
+	s := service(t, executor(t, func(q Request) string {
+		if q.Op == "files.write" {
+			writes++
+			return ""
+		}
+		return `{"ok":true,"result":{}}` + "\n"
+	}))
+	now := retryClock(s)
+	s.wait = func(context.Context, time.Duration) error { t.Fatal("accepted write retried"); return nil }
+	id := retryJob(t, s, now.Add(time.Hour))
+	if err := s.RunOnce(context.Background()); err != nil {
+		t.Fatal(err)
+	}
+	assertJob(t, s, id, background.StateFailed, "EXECUTOR_PROTOCOL")
+	if writes != 1 {
+		t.Fatal(writes)
+	}
+}

package/templates/native-go-delegate/backend/internal/delegate/service.go

@@ -0,0 +1,323 @@
+package delegate
+
+import (
+	"bytes"
+	"context"
+	"dsmapp/internal/api"
+	"dsmapp/internal/background"
+	"encoding/json"
+	"errors"
+	"io"
+	"net/http"
+	"net/url"
+	"os/user"
+	"strconv"
+	"time"
+)
+
+type Subject struct {
+	Username string      `json:"username"`
+	UID      json.Number `json:"uid"`
+}
+
+func (s *Subject) UnmarshalJSON(b []byte) error {
+	var v struct {
+		Username string          `json:"username"`
+		UID      json.RawMessage `json:"uid"`
+	}
+	if e := json.Unmarshal(b, &v); e != nil {
+		return e
+	}
+	var n json.Number
+	if json.Unmarshal(v.UID, &n) != nil {
+		return errors.New("invalid subject UID")
+	}
+	s.Username = v.Username
+	s.UID = n
+	return nil
+}
+
+type Grant struct {
+	DelegationID string    `json:"delegation_id"`
+	Subject      Subject   `json:"subject"`
+	ExpiresAt    time.Time `json:"expires_at"`
+}
+type Capability struct {
+	State  string `json:"state"`
+	Reason string `json:"reason,omitempty"`
+}
+type ExecutorStatus struct {
+	ExecutorDigest string `json:"executor_digest"`
+	PolicyDigest   string `json:"policy_digest"`
+	Version        string `json:"version"`
+	Ready          bool   `json:"ready"`
+}
+type Service struct {
+	ExecutorDigest, PolicyDigest string
+	Client                       *Client
+	Store                        *background.Store
+	Scope, StagingDir            string
+	LookupUID                    func(string) string
+	HTTP                         *http.Client
+	now                          func() time.Time
+	wait                         func(context.Context, time.Duration) error
+}
+
+func LookupUID(name string) string {
+	u, e := user.Lookup(name)
+	if e != nil {
+		return ""
+	}
+	return u.Uid
+}
+func (s *Service) owner(c api.Caller) (background.Submitter, error) {
+	lookup := s.LookupUID
+	if lookup == nil {
+		lookup = LookupUID
+	}
+	o := background.Submitter{User: c.User(), UID: lookup(c.User())}
+	if !c.Authenticated() || !o.Valid() {
+		return o, fail("identity_unavailable")
+	}
+	return o, nil
+}
+func strict(raw json.RawMessage, out any) error {
+	d := json.NewDecoder(bytes.NewReader(raw))
+	d.DisallowUnknownFields()
+	if d.Decode(out) != nil || d.Decode(new(any)) != io.EOF {
+		return api.BadRequest("invalid parameters")
+	}
+	return nil
+}
+func (s *Service) Status(ctx context.Context) Capability {
+	var out ExecutorStatus
+	e := s.Client.Call(ctx, "status", nil, nil, &out)
+	if e != nil {
+		var a *api.Error
+		if errors.As(e, &a) && (a.Code == "EXECUTOR_UNAVAILABLE" || a.Code == "EXECUTOR_TIMEOUT") {
+			return Capability{State: "needs-admin-approval", Reason: a.Code}
+		}
+		return Capability{State: "blocked", Reason: "executor-status-refused"}
+	}
+	if (s.ExecutorDigest != "" && out.ExecutorDigest != s.ExecutorDigest) || (s.PolicyDigest != "" && out.PolicyDigest != s.PolicyDigest) || !out.Ready || out.ExecutorDigest == "" || out.PolicyDigest == "" || out.Version == "" {
+		return Capability{State: "blocked", Reason: "executor-not-ready"}
+	}
+	return Capability{State: "ready"}
+}
+
+type CreateParams struct {
+	JobID string   `json:"job_id"`
+	Ops   []string `json:"ops"`
+	Path  string   `json:"path"`
+	TTL   int      `json:"ttl_seconds"`
+}
+
+func (s *Service) create(ctx context.Context, r *http.Request, in CreateParams) (Grant, error) {
+	var out Grant
+	auth, e := api.DSMSession(r)
+	if e != nil {
+		return out, e
+	}
+	if in.JobID == "" || !validPath(in.Path) || in.TTL <= 0 || in.TTL > 3600 || len(in.Ops) == 0 || len(in.Ops) > 5 {
+		return out, fail("invalid-request")
+	}
+	for _, op := range in.Ops {
+		switch op {
+		case "files.list", "files.info", "files.createFolder", "files.checkPermission", "files.write":
+		default:
+			return out, fail("invalid-request")
+		}
+	}
+	e = s.Client.Call(ctx, "delegate.create", auth, map[string]any{"job_id": in.JobID, "ops": in.Ops, "scope": s.Scope, "path": in.Path, "ttl_seconds": in.TTL}, &out)
+	if e == nil && (out.DelegationID == "" || out.Subject.Username == "" || out.Subject.UIDString() == "" || out.ExpiresAt.IsZero()) {
+		e = fail("EXECUTOR_PROTOCOL")
+	}
+	return out, e
+}
+func (s *Service) revokeJob(ctx context.Context, b background.DelegationBinding) error {
+	return s.Client.Call(ctx, "delegate.revoke", nil, map[string]string{"delegation_id": b.DelegationID, "job_id": b.JobID}, nil)
+}
+func (s *Service) Sweep(ctx context.Context) error {
+	bindings, e := s.Store.DelegationCleanup(ctx)
+	if e != nil {
+		return e
+	}
+	var result error
+	for _, b := range bindings {
+		if e = s.revokeJob(ctx, b); e == nil {
+			e = s.Store.ForgetDelegation(ctx, b.JobID)
+		}
+		result = errors.Join(result, e)
+	}
+	return result
+}
+func (s *Service) Routes() []api.Route {
+	routes := []api.Route{}
+	for _, method := range []string{"delegate.status", "delegate.create", "delegate.list", "delegate.revoke", "delegate.jobs.submit", "delegate.jobs.list", "delegate.jobs.cancel"} {
+		m := method
+		routes = append(routes, api.HandleRequest(m, func(ctx context.Context, c api.Caller, r *http.Request, p json.RawMessage) (any, error) {
+			return s.handle(ctx, c, r, m, p)
+		}))
+	}
+	return routes
+}
+func (s *Service) handle(ctx context.Context, c api.Caller, r *http.Request, method string, p json.RawMessage) (any, error) {
+	if !c.Authenticated() {
+		return nil, fail("session_required")
+	}
+	switch method {
+	case "delegate.status":
+		if e := strict(p, &struct{}{}); e != nil {
+			return nil, e
+		}
+		return s.Status(ctx), nil
+	case "delegate.create":
+		var in CreateParams
+		if e := strict(p, &in); e != nil {
+			return nil, e
+		}
+		return s.create(ctx, r, in)
+	case "delegate.list":
+		if e := strict(p, &struct{}{}); e != nil {
+			return nil, e
+		}
+		auth, e := api.DSMSession(r)
+		if e != nil {
+			return nil, e
+		}
+		var out json.RawMessage
+		e = s.Client.Call(ctx, "delegate.list", auth, nil, &out)
+		return out, e
+	case "delegate.revoke":
+		var in struct {
+			ID string `json:"delegation_id"`
+		}
+		if e := strict(p, &in); e != nil || in.ID == "" {
+			return nil, api.BadRequest("delegation_id required")
+		}
+		auth, e := api.DSMSession(r)
+		if e != nil {
+			return nil, e
+		}
+		// Stop local work first; failed socket revocation remains durable cleanup.
+		owner, err := s.owner(c)
+		if err != nil {
+			return nil, err
+		}
+		jobs, err := s.Store.ListFor(ctx, background.Access{Owner: owner})
+		if err != nil {
+			return nil, jobError(err)
+		}
+		for _, job := range jobs {
+			if job.DelegationID == in.ID {
+				if _, err = s.Store.CancelFor(ctx, job.ID, background.Access{Owner: owner}); err != nil && !errors.Is(err, background.ErrNotCancelable) {
+					return nil, jobError(err)
+				}
+			}
+		}
+		e = s.Client.Call(ctx, "delegate.revoke", auth, map[string]string{"delegation_id": in.ID}, nil)
+		return map[string]bool{"revoked": e == nil}, e
+	}
+	owner, e := s.owner(c)
+	if e != nil {
+		return nil, e
+	}
+	access := background.Access{Owner: owner}
+	switch method {
+	case "delegate.jobs.submit":
+		var in struct {
+			Key string `json:"key"`
+			DownloadInput
+		}
+		if e := strict(p, &in); e != nil {
+			return nil, e
+		}
+		if !validDownload(in.DownloadInput) {
+			return nil, fail("invalid-request")
+		}
+		data, _ := json.Marshal(in.DownloadInput)
+		job, e := s.Store.SubmitDelegated(ctx, background.SubmitRequest{Key: in.Key, Name: in.Name, Data: data, Submitter: owner}, func(id string) (background.DelegationBinding, error) {
+			grant, e := s.create(ctx, r, CreateParams{JobID: id, Ops: []string{"files.write"}, Path: in.Dest, TTL: 3600})
+			if e != nil {
+				return background.DelegationBinding{}, e
+			}
+			if grant.Subject.Username != owner.User || grant.Subject.UIDString() != owner.UID {
+				cleanup, done := context.WithTimeout(context.Background(), 10*time.Second)
+				defer done()
+				s.revokeJob(cleanup, background.DelegationBinding{JobID: id, DelegationID: grant.DelegationID})
+				return background.DelegationBinding{}, fail("identity_unavailable")
+			}
+			return background.DelegationBinding{DelegationID: grant.DelegationID, ExpiresAt: grant.ExpiresAt}, nil
+		}, func(b background.DelegationBinding) {
+			cleanup, done := context.WithTimeout(context.Background(), 10*time.Second)
+			defer done()
+			if s.revokeJob(cleanup, b) == nil {
+				_ = s.Store.ForgetDelegation(cleanup, b.JobID)
+			}
+		})
+		return job, jobError(e)
+	case "delegate.jobs.list":
+		if e := strict(p, &struct{}{}); e != nil {
+			return nil, e
+		}
+		jobs, e := s.Store.ListDelegatedFor(ctx, access)
+		return map[string]any{"jobs": jobs}, jobError(e)
+	case "delegate.jobs.cancel":
+		var in struct {
+			ID string `json:"id"`
+		}
+		if e := strict(p, &in); e != nil {
+			return nil, e
+		}
+		job, e := s.Store.GetFor(ctx, in.ID, access)
+		if e != nil || job.Worker != background.WorkerDownloadV1 {
+			return nil, fail("not_found")
+		}
+		job, e = s.Store.CancelFor(ctx, in.ID, access)
+		if e != nil {
+			return nil, jobError(e)
+		}
+		e = s.Sweep(ctx)
+		if e != nil {
+			return map[string]any{"job": job, "revocation_pending": true}, nil
+		}
+		return map[string]any{"job": job, "revocation_pending": false}, nil
+	}
+	return nil, fail("unsupported")
+}
+func jobError(e error) error {
+	if e == nil {
+		return nil
+	}
+	var a *api.Error
+	if errors.As(e, &a) {
+		return e
+	}
+	codes := map[error]string{background.ErrBusy: "jobs_busy", background.ErrNotFound: "not_found", background.ErrNotCancelable: "not_cancelable", background.ErrKeyConflict: "key_conflict", background.ErrOwnerQueueFull: "queue_full", background.ErrQueueFull: "queue_full", background.ErrOwnerQuota: "quota", background.ErrQuota: "quota", background.ErrInvalid: "invalid-request"}
+	for err, code := range codes {
+		if errors.Is(e, err) {
+			return fail(code)
+		}
+	}
+	return fail("jobs_unavailable")
+}
+
+type DownloadInput struct {
+	URL  string `json:"url"`
+	Dest string `json:"dest"`
+	Name string `json:"name"`
+}
+
+func validDownload(in DownloadInput) bool {
+	u, e := url.Parse(in.URL)
+	return e == nil && (u.Scheme == "http" || u.Scheme == "https") && u.Host != "" && u.User == nil && u.Fragment == "" && len(in.URL) <= 4096 && validPath(in.Dest) && validName(in.Name)
+}
+
+// ParseUID is useful when assembling a trusted job owner from executor output.
+func (s Subject) UIDString() string {
+	n, e := strconv.ParseUint(s.UID.String(), 10, 32)
+	if e != nil || n == 0 {
+		return ""
+	}
+	return strconv.FormatUint(n, 10)
+}