dynamodb: verify the admin PutItem URL key against the table schema

adapter/dynamodb_admin_items.go

@@ -312,7 +312,13 @@ func (d *DynamoDBServer) adminLoadReadableSchema(ctx context.Context, principal
 //   - ErrAdminNotLeader        — follower
 //   - ErrAdminDynamoNotFound   — table absent
 //   - ErrAdminDynamoValidation — empty / malformed input
-func (d *DynamoDBServer) AdminPutItem(ctx context.Context, principal AdminPrincipal, tableName string, item AdminItem) error {
+func (d *DynamoDBServer) AdminPutItem(
+	ctx context.Context,
+	principal AdminPrincipal,
+	tableName string,
+	pathKey map[string]AdminAttributeValue,
+	item AdminItem,
+) error {
 	if !principal.Role.canWrite() {
 		return ErrAdminForbidden
 	}
@@ -331,6 +337,9 @@ func (d *DynamoDBServer) AdminPutItem(ctx context.Context, principal AdminPrinci
 	if err := validateAdminAttributeMapKinds(item.Attributes); err != nil {
 		return err
 	}
+	if err := d.assertPathKeyCoversPrimaryKey(ctx, tableName, pathKey); err != nil {
+		return err
+	}
 	in := putItemInput{
 		TableName: tableName,
 		Item:      adminToInternalAttributeMap(item.Attributes),
@@ -341,6 +350,52 @@ func (d *DynamoDBServer) AdminPutItem(ctx context.Context, principal AdminPrinci
 	return nil
 }
 
+// assertPathKeyCoversPrimaryKey rejects a PUT whose URL key does not
+// name every primary-key attribute the table's schema declares.
+//
+// The HTTP layer already checks that each attribute IT received in the
+// URL is present in the body with the same value, but it has no schema
+// access — so it cannot tell that a composite-key table's URL segment
+// carried only the hash key while the body supplied the range key. The
+// write would then land on a row the URL never fully identified, which
+// is the difference between "update the item this URL names" and
+// "create some other item".
+//
+// Only the adapter can make that judgement, which is why the URL key
+// is plumbed down here rather than validated above.
+func (d *DynamoDBServer) assertPathKeyCoversPrimaryKey(
+	ctx context.Context, tableName string, pathKey map[string]AdminAttributeValue,
+) error {
+	schema, exists, err := d.loadTableSchema(ctx, tableName)
+	if err != nil {
+		return errors.WithStack(err)
+	}
+	if !exists {
+		return ErrAdminDynamoNotFound
+	}
+
+	required := []string{schema.PrimaryKey.HashKey}
+	if schema.PrimaryKey.RangeKey != "" {
+		required = append(required, schema.PrimaryKey.RangeKey)
+	}
+	for _, name := range required {
+		if _, ok := pathKey[name]; !ok {
+			return errors.Wrapf(ErrAdminDynamoValidation,
+				"path key is missing primary key attribute %q", name)
+		}
+	}
+	// Reject extras too: a URL key carrying an attribute the schema
+	// does not treat as part of the primary key means the caller and
+	// the table disagree about identity, and silently ignoring it
+	// would let the mismatch through.
+	if len(pathKey) != len(required) {
+		return errors.Wrapf(ErrAdminDynamoValidation,
+			"path key declares %d attributes but the primary key has %d",
+			len(pathKey), len(required))
+	}
+	return nil
+}
+
 // AdminDeleteItem removes one item by primary key. Write role
 // required.
 //

adapter/dynamodb_admin_items_test.go

@@ -37,6 +37,18 @@ func createTableForItemTests(t *testing.T, srv *DynamoDBServer, name string) {
 	require.NoError(t, err)
 }
 
+// putItemForTest derives the URL path key from the item's "id"
+// attribute, matching the single-hash-key schema
+// createTableForItemTests installs. AdminPutItem now takes the URL key
+// so it can verify the caller named every primary-key attribute.
+func putItemForTest(ctx context.Context, srv *DynamoDBServer, table string, item AdminItem) error {
+	key := map[string]AdminAttributeValue{}
+	if id, ok := item.Attributes["id"]; ok {
+		key["id"] = id
+	}
+	return srv.AdminPutItem(ctx, fullAdminPrincipal, table, key, item)
+}
+
 // TestDynamoDB_AdminPutItem_HappyPath pins the basic write contract:
 // PutItem followed by GetItem returns the stored attributes.
 func TestDynamoDB_AdminPutItem_HappyPath(t *testing.T) {
@@ -53,7 +65,7 @@ func TestDynamoDB_AdminPutItem_HappyPath(t *testing.T) {
 		"active": boolAttr(true),
 		"age":    numberAttr(42),
 	}}
-	require.NoError(t, srv.AdminPutItem(ctx, fullAdminPrincipal, "puttable", item))
+	require.NoError(t, putItemForTest(ctx, srv, "puttable", item))
 
 	got, exists, err := srv.AdminGetItem(ctx, fullAdminPrincipal, "puttable", map[string]AdminAttributeValue{"id": stringAttr("alpha")})
 	require.NoError(t, err)
@@ -101,7 +113,7 @@ func TestDynamoDB_AdminDeleteItem_HappyPath(t *testing.T) {
 	createTableForItemTests(t, srv, "deltable")
 
 	key := map[string]AdminAttributeValue{"id": stringAttr("k1")}
-	require.NoError(t, srv.AdminPutItem(ctx, fullAdminPrincipal, "deltable", AdminItem{Attributes: key}))
+	require.NoError(t, putItemForTest(ctx, srv, "deltable", AdminItem{Attributes: key}))
 	require.NoError(t, srv.AdminDeleteItem(ctx, fullAdminPrincipal, "deltable", key))
 
 	_, exists, err := srv.AdminGetItem(ctx, fullAdminPrincipal, "deltable", key)
@@ -121,8 +133,7 @@ func TestDynamoDB_AdminScanTable_HappyPath(t *testing.T) {
 	createTableForItemTests(t, srv, "scantable")
 
 	for _, id := range []string{"a", "b", "c"} {
-		require.NoError(t, srv.AdminPutItem(ctx, fullAdminPrincipal, "scantable",
-			AdminItem{Attributes: map[string]AdminAttributeValue{"id": stringAttr(id)}}))
+		require.NoError(t, putItemForTest(ctx, srv, "scantable", AdminItem{Attributes: map[string]AdminAttributeValue{"id": stringAttr(id)}}))
 	}
 
 	res, err := srv.AdminScanTable(ctx, fullAdminPrincipal, "scantable", AdminScanOptions{})
@@ -149,8 +160,7 @@ func TestDynamoDB_AdminScanTable_LimitClamping(t *testing.T) {
 	createTableForItemTests(t, srv, "limittable")
 
 	for i := range 5 {
-		require.NoError(t, srv.AdminPutItem(ctx, fullAdminPrincipal, "limittable",
-			AdminItem{Attributes: map[string]AdminAttributeValue{"id": stringAttr("row-" + strconv.Itoa(i))}}))
+		require.NoError(t, putItemForTest(ctx, srv, "limittable", AdminItem{Attributes: map[string]AdminAttributeValue{"id": stringAttr("row-" + strconv.Itoa(i))}}))
 	}
 
 	// Limit=2 — under the cap, exact match.
@@ -178,8 +188,7 @@ func TestDynamoDB_AdminScanTable_CursorRoundTrip(t *testing.T) {
 
 	const sent = 7
 	for i := range sent {
-		require.NoError(t, srv.AdminPutItem(ctx, fullAdminPrincipal, "cursortable",
-			AdminItem{Attributes: map[string]AdminAttributeValue{"id": stringAttr("k" + strconv.Itoa(i))}}))
+		require.NoError(t, putItemForTest(ctx, srv, "cursortable", AdminItem{Attributes: map[string]AdminAttributeValue{"id": stringAttr("k" + strconv.Itoa(i))}}))
 	}
 
 	pageA, err := srv.AdminScanTable(ctx, fullAdminPrincipal, "cursortable", AdminScanOptions{Limit: 3})
@@ -208,7 +217,7 @@ func TestDynamoDB_AdminPutItem_ReadOnlyForbidden(t *testing.T) {
 	srv := nodes[0].dynamoServer
 	createTableForItemTests(t, srv, "rotable")
 
-	err := srv.AdminPutItem(context.Background(), readOnlyAdminPrincipal, "rotable",
+	err := srv.AdminPutItem(context.Background(), readOnlyAdminPrincipal, "rotable", nil,
 		AdminItem{Attributes: map[string]AdminAttributeValue{"id": stringAttr("x")}})
 	require.True(t, errors.Is(err, ErrAdminForbidden))
 }
@@ -247,7 +256,7 @@ func TestDynamoDB_AdminPutItem_EmptyTableName(t *testing.T) {
 	defer shutdown(nodes)
 	srv := nodes[0].dynamoServer
 
-	err := srv.AdminPutItem(context.Background(), fullAdminPrincipal, "  ",
+	err := srv.AdminPutItem(context.Background(), fullAdminPrincipal, "  ", nil,
 		AdminItem{Attributes: map[string]AdminAttributeValue{"id": stringAttr("x")}})
 	require.True(t, errors.Is(err, ErrAdminDynamoValidation))
 }
@@ -307,7 +316,7 @@ func TestDynamoDB_AdminPutItem_MissingTable(t *testing.T) {
 	defer shutdown(nodes)
 	srv := nodes[0].dynamoServer
 
-	err := srv.AdminPutItem(context.Background(), fullAdminPrincipal, "ghost",
+	err := srv.AdminPutItem(context.Background(), fullAdminPrincipal, "ghost", nil,
 		AdminItem{Attributes: map[string]AdminAttributeValue{"id": stringAttr("x")}})
 	require.True(t, errors.Is(err, ErrAdminDynamoNotFound),
 		"want ErrAdminDynamoNotFound; got %v", err)
@@ -386,7 +395,7 @@ func TestDynamoDB_AdminPutItem_RejectsDeepNesting(t *testing.T) {
 	for range maxAttributeValueNestingDepth {
 		cur = AdminAttributeValue{L: []AdminAttributeValue{cur}}
 	}
-	err := srv.AdminPutItem(context.Background(), fullAdminPrincipal, "deep",
+	err := srv.AdminPutItem(context.Background(), fullAdminPrincipal, "deep", nil,
 		AdminItem{Attributes: map[string]AdminAttributeValue{
 			"id":   stringAttr("k"),
 			"deep": cur,
@@ -540,7 +549,7 @@ func TestDynamoDB_AdminPutItem_RejectsZeroFieldAttribute(t *testing.T) {
 	srv := nodes[0].dynamoServer
 	createTableForItemTests(t, srv, "zerokind")
 
-	err := srv.AdminPutItem(context.Background(), fullAdminPrincipal, "zerokind",
+	err := srv.AdminPutItem(context.Background(), fullAdminPrincipal, "zerokind", nil,
 		AdminItem{Attributes: map[string]AdminAttributeValue{
 			"id":    stringAttr("k"),
 			"empty": {}, // no kind field set
@@ -560,7 +569,7 @@ func TestDynamoDB_AdminPutItem_RejectsMultiFieldAttribute(t *testing.T) {
 
 	s := "x"
 	n := "1"
-	err := srv.AdminPutItem(context.Background(), fullAdminPrincipal, "multikind",
+	err := srv.AdminPutItem(context.Background(), fullAdminPrincipal, "multikind", nil,
 		AdminItem{Attributes: map[string]AdminAttributeValue{
 			"id":  stringAttr("k"),
 			"bad": {S: &s, N: &n},
@@ -582,7 +591,7 @@ func TestDynamoDB_AdminPutItem_RejectsNullFalse(t *testing.T) {
 	createTableForItemTests(t, srv, "nullfalse")
 
 	falseVal := false
-	err := srv.AdminPutItem(context.Background(), fullAdminPrincipal, "nullfalse",
+	err := srv.AdminPutItem(context.Background(), fullAdminPrincipal, "nullfalse", nil,
 		AdminItem{Attributes: map[string]AdminAttributeValue{
 			"id":  stringAttr("k"),
 			"bad": {NULL: &falseVal},
@@ -593,9 +602,89 @@ func TestDynamoDB_AdminPutItem_RejectsNullFalse(t *testing.T) {
 	// Sanity: NULL=true is valid and round-trips.
 	trueVal := true
 	err = srv.AdminPutItem(context.Background(), fullAdminPrincipal, "nullfalse",
+		map[string]AdminAttributeValue{"id": stringAttr("k")},
 		AdminItem{Attributes: map[string]AdminAttributeValue{
 			"id":   stringAttr("k"),
 			"good": {NULL: &trueVal},
 		}})
 	require.NoError(t, err, "NULL=true must be accepted")
 }
+
+// TestDynamoDB_AdminPutItem_RejectsPathKeyThatMissesThePrimaryKey
+// closes the gap the data-browser design tracked separately: the HTTP
+// layer verifies that each attribute IT received in the URL matches
+// the body, but has no schema access, so it cannot tell that the URL
+// named only part of a composite primary key. The write would then
+// land on a row the URL never fully identified.
+func TestDynamoDB_AdminPutItem_RejectsPathKeyThatMissesThePrimaryKey(t *testing.T) {
+	t.Parallel()
+	nodes, _, _ := createNode(t, 1)
+	defer shutdown(nodes)
+	srv := nodes[0].dynamoServer
+	ctx := context.Background()
+
+	_, err := srv.AdminCreateTable(ctx, fullAdminPrincipal, AdminCreateTableInput{
+		TableName:    "composite",
+		PartitionKey: AdminAttribute{Name: "pk", Type: "S"},
+		SortKey:      &AdminAttribute{Name: "sk", Type: "S"},
+	})
+	require.NoError(t, err)
+
+	item := AdminItem{Attributes: map[string]AdminAttributeValue{
+		"pk":   stringAttr("tenant-1"),
+		"sk":   stringAttr("order-9"),
+		"note": stringAttr("hello"),
+	}}
+
+	// URL named only the hash key: the body's sk decides which row is
+	// written, which is not the row the URL identifies.
+	err = srv.AdminPutItem(ctx, fullAdminPrincipal, "composite",
+		map[string]AdminAttributeValue{"pk": stringAttr("tenant-1")}, item)
+	require.ErrorIs(t, err, ErrAdminDynamoValidation)
+
+	// The full key is accepted.
+	require.NoError(t, srv.AdminPutItem(ctx, fullAdminPrincipal, "composite",
+		map[string]AdminAttributeValue{
+			"pk": stringAttr("tenant-1"),
+			"sk": stringAttr("order-9"),
+		}, item))
+}
+
+// TestDynamoDB_AdminPutItem_RejectsPathKeyWithExtraAttributes covers
+// the other direction: a URL key carrying an attribute the schema does
+// not treat as part of the primary key means the caller and the table
+// disagree about identity.
+func TestDynamoDB_AdminPutItem_RejectsPathKeyWithExtraAttributes(t *testing.T) {
+	t.Parallel()
+	nodes, _, _ := createNode(t, 1)
+	defer shutdown(nodes)
+	srv := nodes[0].dynamoServer
+	ctx := context.Background()
+	createTableForItemTests(t, srv, "extrakey")
+
+	item := AdminItem{Attributes: map[string]AdminAttributeValue{
+		"id":   stringAttr("a"),
+		"name": stringAttr("Alice"),
+	}}
+	err := srv.AdminPutItem(ctx, fullAdminPrincipal, "extrakey",
+		map[string]AdminAttributeValue{
+			"id":   stringAttr("a"),
+			"name": stringAttr("Alice"), // not part of the primary key
+		}, item)
+	require.ErrorIs(t, err, ErrAdminDynamoValidation)
+}
+
+// TestDynamoDB_AdminPutItem_ReportsMissingTable pins that the schema
+// lookup the key check performs surfaces an absent table as not-found
+// rather than as a validation error.
+func TestDynamoDB_AdminPutItem_ReportsMissingTable(t *testing.T) {
+	t.Parallel()
+	nodes, _, _ := createNode(t, 1)
+	defer shutdown(nodes)
+	srv := nodes[0].dynamoServer
+
+	err := srv.AdminPutItem(context.Background(), fullAdminPrincipal, "no-such-table",
+		map[string]AdminAttributeValue{"id": stringAttr("a")},
+		AdminItem{Attributes: map[string]AdminAttributeValue{"id": stringAttr("a")}})
+	require.ErrorIs(t, err, ErrAdminDynamoNotFound)
+}

docs/design/2026_05_22_implemented_admin_data_browser.md

@@ -24,7 +24,7 @@ Final milestone landed 2026-05-24. All six phases shipped between
 Notable in-flight design adjustments documented from PR review:
 - Empty `L` / `M` Dynamo attributes preserve their type tag on the wire via a custom `MarshalJSON` (Gemini medium, Codex P1 on #813). The struct tags stay as `omitempty`-decorated documentation; the custom marshal overrides.
 - Path-segment validation decodes via `url.PathUnescape` before validating, so tables named e.g. `foo bar` are reachable as `/tables/foo%20bar` while `%2F` / `%2e%2e` still close the path-traversal class (Codex P1 on #813).
-- The HTTP layer cannot reject a body that declares MORE primary-key columns than the URL key (no schema access); the principled fix (plumb the URL key into `AdminPutItem` so the adapter can compare against the schema-derived primary key) crosses the Phase-2a adapter boundary and is tracked separately (Codex P2 on #813).
+- ~~The HTTP layer cannot reject a body that declares MORE primary-key columns than the URL key~~ — **fixed.** The URL key is now plumbed into `AdminPutItem`, which loads the table schema and requires the key to name exactly the primary-key attributes (hash, plus range when the table has one). A URL naming only part of a composite key, or carrying an attribute the schema does not treat as part of the primary key, is rejected with `ErrAdminDynamoValidation` (Codex P2 on #813).
 - SPA bundle output (`internal/admin/dist/assets/*`) stays `.gitignored`; CI rebuilds from source on every release.
 
 ---

internal/admin/dynamo_handler.go

@@ -79,7 +79,11 @@ type TablesSource interface {
 	// adapter package's Admin*Item methods.
 	AdminScanItems(ctx context.Context, principal AuthPrincipal, table string, opts AdminScanItemsOptions) (AdminScanItemsResult, error)
 	AdminGetItem(ctx context.Context, principal AuthPrincipal, table string, key map[string]AdminAttributeValue) (*AdminItem, bool, error)
-	AdminPutItem(ctx context.Context, principal AuthPrincipal, table string, item AdminItem) error
+	// AdminPutItem receives the URL key alongside the body so the
+	// adapter — which has schema access the HTTP layer lacks — can
+	// verify the key names every primary-key attribute the table
+	// declares.
+	AdminPutItem(ctx context.Context, principal AuthPrincipal, table string, key map[string]AdminAttributeValue, item AdminItem) error
 	AdminDeleteItem(ctx context.Context, principal AuthPrincipal, table string, key map[string]AdminAttributeValue) error
 }
 

internal/admin/dynamo_handler_test.go

@@ -107,7 +107,7 @@ func (s *stubTablesSource) AdminGetItem(_ context.Context, _ AuthPrincipal, _ st
 	return nil, false, nil
 }
 
-func (s *stubTablesSource) AdminPutItem(_ context.Context, _ AuthPrincipal, _ string, _ AdminItem) error {
+func (s *stubTablesSource) AdminPutItem(_ context.Context, _ AuthPrincipal, _ string, _ map[string]AdminAttributeValue, _ AdminItem) error {
 	return nil
 }
 

internal/admin/dynamo_items_handler.go

@@ -247,7 +247,7 @@ func (h *DynamoHandler) handleItemPut(w http.ResponseWriter, r *http.Request, ta
 		writeJSONError(w, http.StatusBadRequest, "invalid_request", err.Error())
 		return
 	}
-	if err := h.source.AdminPutItem(r.Context(), principal, table, item); err != nil {
+	if err := h.source.AdminPutItem(r.Context(), principal, table, key, item); err != nil {
 		h.writeItemsError(w, r, "put", table, err)
 		return
 	}

internal/admin/dynamo_items_handler_test.go

@@ -120,7 +120,7 @@ func itemMatchesKey(attrs, key map[string]AdminAttributeValue) bool {
 	return true
 }
 
-func (s *stubItemsSource) AdminPutItem(_ context.Context, principal AuthPrincipal, table string, item AdminItem) error {
+func (s *stubItemsSource) AdminPutItem(_ context.Context, principal AuthPrincipal, table string, key map[string]AdminAttributeValue, item AdminItem) error {
 	s.lastPutPrincipal = principal
 	if s.nextErr != nil {
 		err := s.nextErr

main_admin.go

@@ -763,9 +763,9 @@ func (b *dynamoTablesBridge) AdminGetItem(ctx context.Context, principal admin.A
 	return &admin.AdminItem{Attributes: adapterToAdminAttributeMap(item.Attributes)}, true, nil
 }
 
-func (b *dynamoTablesBridge) AdminPutItem(ctx context.Context, principal admin.AuthPrincipal, table string, item admin.AdminItem) error {
+func (b *dynamoTablesBridge) AdminPutItem(ctx context.Context, principal admin.AuthPrincipal, table string, key map[string]admin.AdminAttributeValue, item admin.AdminItem) error {
 	adapterItem := adapter.AdminItem{Attributes: adminToAdapterAttributeMap(item.Attributes)}
-	if err := b.server.AdminPutItem(ctx, convertAdminPrincipal(principal), table, adapterItem); err != nil {
+	if err := b.server.AdminPutItem(ctx, convertAdminPrincipal(principal), table, adminToAdapterAttributeMap(key), adapterItem); err != nil {
 		return translateAdminItemsError(err)
 	}
 	return nil

main_admin_forward_test.go

@@ -258,7 +258,7 @@ func (dummyTablesSource) AdminGetItem(_ context.Context, _ admin.AuthPrincipal,
 	panic("dummyTablesSource.AdminGetItem should not be invoked")
 }
 
-func (dummyTablesSource) AdminPutItem(_ context.Context, _ admin.AuthPrincipal, _ string, _ admin.AdminItem) error {
+func (dummyTablesSource) AdminPutItem(_ context.Context, _ admin.AuthPrincipal, _ string, _ map[string]admin.AdminAttributeValue, _ admin.AdminItem) error {
 	panic("dummyTablesSource.AdminPutItem should not be invoked")
 }