Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 19 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -98,13 +98,20 @@ keys act as their user with the Viewer role. External-subject keys act as an
active registered agent whose immutable handle equals the subject.
The rules are in [`design/API.md`](design/API.md#access-keys-v0111).

### Agent protocol (0.1.13)

An Admin registers agents through `POST /api/tracker/v1/agents`, with a handle,
display name, description and accountable person owner. Keys are issued and
revoked by the platform, never by Tracker. Disabling an agent rejects all its
keys, cancels its non-terminal runs and withdraws its open requests. Names and
owners may change; handles cannot. Existing issue attribution is not rewritten.
### Agent protocol (0.1.14)

An agent registers itself: the first call of a new external-subject key is
`POST /api/tracker/v1/agents/register` with a display name, description and
its accountable person owner; the handle is the key's subject. Minting that
key needs a Project admin, which is the admission decision. The owner is
claimed by the agent, so the Agents page marks self-registered agents with the
key that registered them. An Admin can also register an agent directly through
`POST /api/tracker/v1/agents`. Keys are issued and revoked by the platform,
never by Tracker. Disabling an agent rejects all its keys (it cannot register
again), cancels its non-terminal runs and withdraws its open requests. Names
and owners may change; handles cannot. Existing issue attribution is not
rewritten. The rules are in
[`design/API.md`](design/API.md#self-registration-v0114).

Agents poll `/inbox` and `/events`. Initialize the event cursor without `after`,
then poll with `after=next`; sequence allocation and the represented write
Expand Down Expand Up @@ -169,14 +176,14 @@ a required BuildKit secret, never through build arguments or committed files.

## Catalog and release

The next app release is **0.1.13**, also recorded in `web/package.json`.
The next app release is **0.1.14**, also recorded in `web/package.json`.
`catalog/entry.yaml` carries no committed version: the first tag (`v0.1.0`)
created `versions[]` with `ghcr.io/appthrust/tracker@sha256:<index-digest>`,
stream `0.1`; later tags append at publication time. Do not add a version with
an unbuilt or placeholder image digest. OpenAPI's `info.version` describes the
API schema, not the app release. This repository has no hand-maintained changelog.

After the release prerequisites are available, push the SemVer tag `v0.1.13`.
After the release prerequisites are available, push the SemVer tag `v0.1.14`.
The tag workflow:

1. Performs one multi-platform build on `ubuntu-24.04` for Linux amd64 and arm64,
Expand All @@ -196,8 +203,8 @@ The tag workflow:
Publication commands used by the workflow:

```sh
bun hack/publish-entry.ts submit --version 0.1.13 --digest sha256:<image-index-digest>
bun hack/publish-entry.ts await --version 0.1.13 --digest sha256:<image-index-digest>
bun hack/publish-entry.ts submit --version 0.1.14 --digest sha256:<image-index-digest>
bun hack/publish-entry.ts await --version 0.1.14 --digest sha256:<image-index-digest>
```

Writers are serialized by `tracker-catalog-publish`; the workflow is guarded to
Expand All @@ -218,7 +225,7 @@ After publication, each estate's `AppCatalogSource` syncs the signed catalog.
Install Issues from the Project Marketplace (Directory is an automatic
dependency). Existing `follow` installations on stream `0.1` roll to the new
version; `pinned` installations show `UpdateAvailable` and require an explicit
version update. Confirm the installation is Ready, `/releasez` reports `0.1.13`,
version update. Confirm the installation is Ready, `/releasez` reports `0.1.14`,
the Project lists the `tracker` Access Key space as Ready, and an exchanged key reads `/api/tracker/v1/me`. These are release steps,
not actions performed by a source-only version bump.

Expand Down
17 changes: 17 additions & 0 deletions cmd/server/internal/api/agents.go
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
package api

import (
"github.com/appthrust/appserver-go/appserver/httpx"
"github.com/appthrust/tracker/cmd/server/internal/domain"
"github.com/appthrust/tracker/cmd/server/internal/store"
"strconv"
Expand Down Expand Up @@ -40,6 +41,22 @@ func (a *API) agentCreate(s *request) (any, int, error) {
return &item, 201, err
}

func (a *API) agentRegister(s *request) (any, int, error) {
if !s.actor.Key || s.actor.Kind != "agent" {
return nil, 0, httpx.Forbidden()
}
var input store.AgentRegister
if err := decode(s, &input); err != nil {
return nil, 0, err
}
item, created, err := s.tx.RegisterAgent(input, s.actor, s.keyName)
status := 200
if created {
status = 201
}
return &item, status, err
}

func (a *API) inbox(s *request) (any, int, error) {
list, err := s.tx.Inbox(s.actor)
return items[domain.InboxItem]{Items: list}, 200, err
Expand Down
218 changes: 218 additions & 0 deletions cmd/server/internal/api/agents_test.go
Original file line number Diff line number Diff line change
@@ -1,10 +1,19 @@
package api

import (
"crypto/ecdsa"
"crypto/elliptic"
"crypto/rand"
"encoding/base64"
"encoding/json"
"net/http"
"net/http/httptest"
"strings"
"testing"
"time"

"github.com/appthrust/appserver-go/accesskey"
"github.com/appthrust/appserver-go/appserver/identity"
"github.com/appthrust/tracker/cmd/server/internal/domain"
"github.com/appthrust/tracker/cmd/server/internal/store"
"github.com/stretchr/testify/require"
Expand Down Expand Up @@ -153,3 +162,212 @@ func TestAgentLeaseWaitingAndDisabledBoundaries(t *testing.T) {
require.Equal(t, "assigneeSub", issues[0].(map[string]any)["path"])
}
}

func TestAgentSelfRegistration(t *testing.T) {
private, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
require.NoError(t, err)
signer := accesskey.NewES256Signer("registration-test", private)
jwks := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if r.URL.Path != "/access/jwks.json" {
http.NotFound(w, r)
return
}
_ = json.NewEncoder(w).Encode(signer.JWKS())
}))
t.Cleanup(jwks.Close)
issuer := accesskey.IssuerURL(jwks.URL)
h := newHarnessTrusting(t, identity.Trust{AccessIssuer: issuer, AccessAudience: "tracker"})
assertion := func(subject accesskey.Subject, keyName string, scopes ...string) string {
value, err := signer.Sign(accesskey.Claims{
Issuer: issuer, Audience: "tracker", Project: "pj-test", KeyName: keyName, Subject: subject,
Scopes: scopes, JTI: "test", IssuedAt: time.Now(), ExpiresAt: time.Now().Add(time.Minute),
})
require.NoError(t, err)
return "Bearer " + value
}
external := func(handle string, scopes ...string) string {
return assertion(accesskey.Subject{Kind: accesskey.SubjectExternal, ID: handle}, "ak-register", scopes...)
}
bearer := external("self-agent", scopeRead, scopeWrite)
body := []byte(`{"name":"Self Agent","description":"Registers itself","ownerSub":"owner"}`)
checkBlockedRoutes := func(t *testing.T) {
t.Helper()
for _, route := range (&API{}).routes() {
if route.pattern == "POST /agents/register" || route.pattern == "GET /agent-guide" {
continue
}
method, path, _ := strings.Cut(route.pattern, " ")
path = strings.ReplaceAll(path, "{id}", "01JABCDEFGHJKMNPQRSTVWXYZ0")
data := rawCall(t, h, bearer, method, path, "", []byte(`{}`), 403)
require.Contains(t, string(data), `"error":"key_subject"`, route.pattern)
}
data := rawCall(t, h, bearer, "GET", "/people/person-1/avatar", "", nil, 403)
require.Contains(t, string(data), `"error":"key_subject"`)
guide := rawCall(t, h, bearer, "GET", "/agent-guide", "", nil, 200)
require.Contains(t, string(guide), "POST /agents/register")
}
t.Run("unregistered routes", checkBlockedRoutes)
data := rawCall(t, h, bearer, "GET", "/me", "", nil, 403)
require.Contains(t, string(data), "POST /api/tracker/v1/agents/register")

// Reads and user-key writes cannot supply the owner's signed-in name.
rawCall(t, h, "Bearer "+token("read-owner"), "GET", "/me", "", nil, 200)
userKey := assertion(accesskey.Subject{Kind: accesskey.SubjectUser, ID: "key-owner"}, "ak-user", scopeRead, scopeWrite)
rawCall(t, h, userKey, "POST", "/issues", "", []byte(`{"title":"Only a key wrote","type":"task"}`), 201)
for _, owner := range []string{"unknown-owner", "read-owner", "key-owner", "agent:01JABCDEFGHJKMNPQRSTVWXYZ0", ""} {
t.Run("invalid owner "+owner, func(t *testing.T) {
input, err := json.Marshal(map[string]string{"name": "Self Agent", "ownerSub": owner})
require.NoError(t, err)
data := rawCall(t, h, bearer, "POST", "/agents/register", "", input, 400)
var failure struct {
Code string `json:"error"`
Issues []domain.FieldError `json:"issues"`
}
require.NoError(t, json.Unmarshal(data, &failure))
require.Equal(t, "invalid", failure.Code)
require.Len(t, failure.Issues, 1)
require.Equal(t, "ownerSub", failure.Issues[0].Path)
})
}
for _, tc := range []struct {
name, bearer, code string
status int
}{
{"user key", userKey, "forbidden", 403},
{"signed-in admin", "Bearer " + token("admin"), "forbidden", 403},
{"signed-in person", "Bearer " + token("owner"), "forbidden", 403},
{"read-only external key", external("self-agent", scopeRead), "insufficient_scope", 403},
{"invalid handle", external("Invalid_handle", scopeWrite), "invalid", 400},
} {
t.Run(tc.name, func(t *testing.T) {
data := rawCall(t, h, tc.bearer, "POST", "/agents/register", "", body, tc.status)
require.Contains(t, string(data), `"error":"`+tc.code+`"`)
})
}
claims, err := json.Marshal(map[string]string{"sub": "owner", "name": "Olivia Owner", "email": "owner@example.test"})
require.NoError(t, err)
session := "Bearer " + base64.RawURLEncoding.EncodeToString([]byte(`{"alg":"none"}`)) + "." + base64.RawURLEncoding.EncodeToString(claims) + "."
rawCall(t, h, session, "POST", "/issues", "", []byte(`{"title":"Signed-in owner","type":"task"}`), 201)
for _, tc := range []struct {
name, body string
}{
{"empty name", `{"name":"","ownerSub":"owner"}`},
{"blank name", `{"name":" ","ownerSub":"owner"}`},
{"long name", `{"name":"` + strings.Repeat("あ", 201) + `","ownerSub":"owner"}`},
{"long description", `{"name":"Agent","description":"` + strings.Repeat("é", 2049) + `","ownerSub":"owner"}`},
{"body handle", `{"name":"Agent","ownerSub":"owner","handle":"other-agent"}`},
{"body provenance", `{"name":"Agent","ownerSub":"owner","registeredByKey":"ak-forged"}`},
} {
t.Run(tc.name, func(t *testing.T) {
data := rawCall(t, h, bearer, "POST", "/agents/register", "", []byte(tc.body), 400)
require.Contains(t, string(data), `"error":"invalid"`)
})
}

eventsBefore := call[map[string]any](h, "admin", "GET", "/events", nil, 200)
data = rawCall(t, h, bearer, "POST", "/agents/register", "register-start", body, 201)
var agent domain.Agent
require.NoError(t, json.Unmarshal(data, &agent))
require.Equal(t, "self-agent", agent.Handle)
require.Equal(t, "Self Agent", agent.Name)
require.Equal(t, "Registers itself", agent.Description)
require.Equal(t, domain.Person{Sub: "owner", Name: "Olivia Owner"}, agent.Owner)
require.NotNil(t, agent.RegisteredByKey)
require.Equal(t, "ak-register", *agent.RegisteredByKey)
require.False(t, agent.Disabled)
require.NoError(t, h.database.InWorkspace(t.Context(), "pj-test", false, func(tx *store.Tx) error {
stored, err := tx.Agent(agent.ID)
require.NoError(t, err)
require.Equal(t, agent.Owner, stored.Owner)
require.Equal(t, agent.RegisteredByKey, stored.RegisteredByKey)
return nil
}))
for _, input := range [][]byte{body, []byte(`{"name":"","description":"Ignored","ownerSub":"agent:ignored"}`)} {
data = rawCall(t, h, bearer, "POST", "/agents/register", "register-start", input, 200)
var existing domain.Agent
require.NoError(t, json.Unmarshal(data, &existing))
require.Equal(t, agent.ID, existing.ID)
require.Equal(t, agent.Name, existing.Name)
require.Equal(t, agent.Description, existing.Description)
require.Equal(t, agent.Owner, existing.Owner)
require.Equal(t, agent.RegisteredByKey, existing.RegisteredByKey)
require.Equal(t, agent.CreatedAt, existing.CreatedAt)
require.Equal(t, agent.UpdatedAt, existing.UpdatedAt)
}
data = rawCall(t, h, bearer, "POST", "/agents/register", strings.Repeat("k", 129), body, 200)
require.Contains(t, string(data), `"id":"`+agent.ID+`"`, "the idempotency header is ignored, not validated")
eventsAfter := call[map[string]any](h, "admin", "GET", "/events", nil, 200)
require.Equal(t, eventsBefore, eventsAfter, "registration must not emit an issue event")
data = rawCall(t, h, bearer, "POST", "/agents/register", "", []byte(`{"name":123,"ownerSub":"owner"}`), 400)
require.Contains(t, string(data), `"error":"invalid"`, "an existing agent must still decode the body shape")
data = rawCall(t, h, bearer, "GET", "/me", "", nil, 200)
require.Contains(t, string(data), `"kind":"agent"`)
require.Contains(t, string(data), `"sub":"agent:`+agent.ID+`"`)

rotated := assertion(accesskey.Subject{Kind: accesskey.SubjectExternal, ID: "self-agent"}, "ak-rotated", scopeWrite)
data = rawCall(t, h, rotated, "POST", "/agents/register", "", body, 200)
var existing domain.Agent
require.NoError(t, json.Unmarshal(data, &existing))
require.Equal(t, agent.RegisteredByKey, existing.RegisteredByKey)
patched := call[domain.Agent](h, "admin", "PATCH", "/agents/"+agent.ID, map[string]string{"name": "Renamed", "description": "Updated", "ownerSub": "admin"}, 200)
require.Equal(t, agent.RegisteredByKey, patched.RegisteredByKey)
call[any](h, "admin", "PATCH", "/agents/"+agent.ID, map[string]string{"registeredByKey": "ak-forged"}, 400)
disabled := call[domain.Agent](h, "admin", "PATCH", "/agents/"+agent.ID, map[string]bool{"disabled": true}, 200)
require.Equal(t, agent.RegisteredByKey, disabled.RegisteredByKey)
data = rawCall(t, h, bearer, "POST", "/agents/register", "register-start", body, 403)
require.Contains(t, string(data), `"error":"key_subject"`)
require.Contains(t, string(data), "The access key subject is not an active registered agent")
t.Run("disabled routes", checkBlockedRoutes)
agents := call[items[domain.Agent]](h, "admin", "GET", "/agents?includeDisabled=true", nil, 200)
require.Len(t, agents.Items, 1)
require.True(t, agents.Items[0].Disabled)
require.Equal(t, patched.Name, agents.Items[0].Name)
require.Equal(t, patched.Owner, agents.Items[0].Owner)
require.Equal(t, agent.RegisteredByKey, agents.Items[0].RegisteredByKey)

// Registration is allowed with write alone, and uses character/byte limits.
limits := []byte(`{"name":"` + strings.Repeat("あ", 200) + `","description":"` + strings.Repeat("é", 2048) + `","ownerSub":"owner"}`)
rawCall(t, h, external("limit-agent", scopeWrite), "POST", "/agents/register", "", limits, 201)
adminAgent := rawCall(t, h, "Bearer "+token("admin"), "POST", "/agents", "", []byte(`{"handle":"admin-agent","name":"Admin Agent","ownerSub":"admin"}`), 201)
require.Contains(t, string(adminAgent), `"registeredByKey":null`)
data = rawCall(t, h, external("admin-agent", scopeWrite), "POST", "/agents/register", "", body, 200)
require.Contains(t, string(data), `"registeredByKey":null`, "self-registration cannot take credit for an Admin-created agent")
}

func TestAgentSelfRegistrationContract(t *testing.T) {
allowed := []string{}
for _, route := range (&API{}).routes() {
if route.unregistered {
allowed = append(allowed, route.pattern)
}
}
require.ElementsMatch(t, []string{"POST /agents/register", "GET /agent-guide"}, allowed)
var document struct {
Components struct {
Schemas map[string]struct {
Properties map[string]json.RawMessage `json:"properties"`
Required []string `json:"required"`
AdditionalProperties bool `json:"additionalProperties"`
} `json:"schemas"`
} `json:"components"`
Paths map[string]map[string]struct {
Responses map[string]json.RawMessage `json:"responses"`
} `json:"paths"`
}
require.NoError(t, json.Unmarshal(openapiDocument, &document))
agent := document.Components.Schemas["Agent"]
require.Contains(t, agent.Required, "registeredByKey")
var provenance struct {
AnyOf []map[string]string `json:"anyOf"`
}
require.NoError(t, json.Unmarshal(agent.Properties["registeredByKey"], &provenance))
require.ElementsMatch(t, []map[string]string{{"type": "string"}, {"type": "null"}}, provenance.AnyOf)
input := document.Components.Schemas["AgentRegister"]
require.ElementsMatch(t, []string{"name", "ownerSub"}, input.Required)
require.NotContains(t, input.Properties, "handle")
require.NotContains(t, input.Properties, "registeredByKey")
require.False(t, input.AdditionalProperties)
for _, status := range []string{"200", "201", "400", "401", "403", "503"} {
require.Contains(t, document.Paths["/agents/register"]["post"].Responses, status)
}
}
26 changes: 16 additions & 10 deletions cmd/server/internal/api/api.go
Original file line number Diff line number Diff line change
Expand Up @@ -29,19 +29,20 @@ type API struct {
mux *http.ServeMux
}
type request struct {
r *http.Request
w http.ResponseWriter
tx *store.Tx
actor domain.Actor
bearer string
r *http.Request
w http.ResponseWriter
tx *store.Tx
actor domain.Actor
bearer string
keyName string
}
type endpoint func(*request) (any, int, error)

func New(database *store.Store, auth *identity.Authenticator, upstream *platformclient.Client, people *directory.Client, workspace string) http.Handler {
a := &API{store: database, identity: auth, platform: upstream, directory: people, workspace: workspace, mux: http.NewServeMux()}
a.mux.HandleFunc("GET /api/tracker/v1/openapi.json", a.openapi)
for _, route := range a.routes() {
a.route(route.pattern, route.mutation, route.roles, route.handler)
a.route(route.pattern, route.mutation, route.roles, route.unregistered, route.handler)
}
a.mux.HandleFunc("GET /api/tracker/v1/people/{id}/avatar", a.avatar)
a.mux.HandleFunc("/", func(w http.ResponseWriter, _ *http.Request) { httpx.WriteError(w, httpx.NotFound(), "tracker") })
Expand All @@ -60,7 +61,7 @@ func (a *API) ServeHTTP(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Cache-Control", "no-store")
a.mux.ServeHTTP(w, r)
}
func (a *API) route(pattern string, mutation, roles bool, fn endpoint) {
func (a *API) route(pattern string, mutation, roles, unregistered bool, fn endpoint) {
method, path, _ := bytes.Cut([]byte(pattern), []byte(" "))
a.mux.HandleFunc(string(method)+" /api/tracker/v1"+string(path), func(w http.ResponseWriter, r *http.Request) {
ctx, cancel := context.WithTimeout(r.Context(), 30*time.Second)
Expand All @@ -81,6 +82,7 @@ func (a *API) route(pattern string, mutation, roles bool, fn endpoint) {
// The assertion is addressed to Tracker only: it is never forwarded
// to Directory. The person's name comes from Tracker's own record.
s.actor = actor
s.keyName = claims.Principal.KeyName
if mutation {
log.Printf("tracker access key mutation: %s %s key=%q subject=%q request_id=%q", r.Method, r.URL.Path, claims.Principal.KeyName, actor.Sub, r.Header.Get("X-Request-Id"))
}
Expand Down Expand Up @@ -124,10 +126,14 @@ func (a *API) route(pattern string, mutation, roles bool, fn endpoint) {
if key && s.actor.Kind == "agent" {
actor, err := tx.AgentBySubject(s.actor.Sub)
if err != nil {
return err
var response *httpx.Error
if !unregistered || !errors.As(err, &response) || response.Code != "key_subject" {
return err
}
} else {
actor.Scopes = s.actor.Scopes
s.actor = actor
}
actor.Scopes = s.actor.Scopes
s.actor = actor
} else if key {
name, err := tx.KnownName(s.actor.Sub)
if err != nil {
Expand Down
2 changes: 1 addition & 1 deletion cmd/server/internal/api/collaboration_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -191,7 +191,7 @@ func TestAgentGuideAndOpenAPIShapes(t *testing.T) {
require.Contains(t, document.Components.Schemas, name)
}
for path, methods := range document.Paths {
if operation, ok := methods["post"]; ok && !strings.HasSuffix(path, "/attachments") {
if operation, ok := methods["post"]; ok && path != "/agents/register" && !strings.HasSuffix(path, "/attachments") {
parameters, err := json.Marshal(operation["parameters"])
require.NoError(t, err)
require.Contains(t, string(parameters), "Idempotency-Key", path)
Expand Down
Loading